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TOPIC I 


Debugging Programs on Multics . ...e. 
Types of Programming Errors . .... 
List of Debugging Tools .... es 
Other Programming and Debugging Tools 
Source-Level Debugging. . ». « « « « « 
Object Level Debugging, «. «> « <-<s: « « 


t-- 
! 
[od 


e e ® ° e 


7 e s a e 


e e 8 e 8 


Topic I 


OBJECTIVES: 


DEBUGGING PROGRAMS ON MULTICS Topic I 


Ureon completion of this topic, students should be able to: 


41. Describe 
errors. 


3. List some 


4, Outline, 
debusging 


Multics 


the methods used to find and correct syntactical 


of the more common source-level debussging tools. 


in general termss the concepts of source-level 
as orprosed to obJect~-level debusgins. 


£4 rel 


TYPES OF PROGRAMMING ERRORS 


3 TWO KINDS OF ERRORS (BUGS) COMMONLY OCCUR IN PROGRAMS 


SYNTAX ERRORS 


re 


[. TYPING ERRORS 


JT MISUSE OF A LANGUAGE STATEMENT 


- JT SEMANTIC ERRORS 


I SPECIFYING THE WRONG DATA 


USING DATA INCORRECTLY 


fo) 


ATTEMPTING TO REFERENCE MORE DATA THAN [IS PRESE 


vad 
ri 


PERFORMING INVALID OPERATIONS ON THE DATA 


one] 1, 


m4 
i) 
re 
td 
hy 
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z 
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Nie 
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ry) 
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TYPES OF PROGRAMMING ERRORS 


% SYNTAX ERRORS 


J CAN BE DETECTED BY 
J] PROOFREADING THE PROGRAM 


IT COMPILING THE PROGRAM AND OBSERVING THE ERROR DIAGNOSTIC 
MESSAGES 


[ CAN BE CORRECTED BY 


I EDITING THE SOURCE PROGRAM TO CORRECT THE ERRORS (DIAGNOSED 
BY THE COMPILER OR FOUND DURING PROOFREADING) 


T RECOMPILING THE SOURCE 


J REPEATING THIS PROCESS UNTIL NO MORE ERRORS ARE DIAGNOSED 
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TYPES OF PROGRAMMING ERRORS 


® SEMANTIC ERRORS 


I PROOFREADING THE PROGRAM 

[I INSERTING TEMPORARY STATEMENTS IN THE PROGRAM SOURCE TO PRINT 
INFORMATION ABOUT DATA VALUES, FLOW OF CONTROL, ETC. 
1 ARE INTERMEDIATE DATA VALUES CORRECT? 


1 DOES THE POINT OF EXECUTION FLOW THROUGH THE PROGRAM IN 
THE EXPECTED WAY? 


I RUNNING THE PROGRAM AND OBSERVING 
I WHETHER OR NOT THE PROGRAM RUNS TO COMPLETION 
1 DOES THE PROGRAM GO INTO A LOOP? 


[I DOES AN UNEXPECTED ERROR CONDITION OCCUR WHICH HALTS 
PROGRAM EXECUTION? 


i a es hed We td adn 


J] WHETHER OR NOT THE PROGRAM PRODUCES THE EXPECTED RESULTS 


I DOES THE PROGRAM PRODUCE CORRECT OUTPUT DATA? 


= 


{| DOES THE PROGRAM DIAGNOSE INCORRECT INPUT DATA? 


1 CAN BE CORRECTED BY 
I IDENTIFYING THE POINT OF ERROR 
I EDITING THE SOURCE PROGRAM TO CORRECT THE ERRORS 


IT RECOMPILING THE SOURCE 
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TYPES OF PROGRAMMING ERRORS 


I REPEATING THIS PROCESS UNTIL THE PROGRAM OPERATES CORRECTLY 
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LIST OF DEBUGGING TOOLS 


® MAJOR TOOLS FOR DIAGNOSING 


I SYNTAX ERRORS 


I THE COMPILERS 


I 
t 


r 
i 


pil 
cobol 


Fortran 


[| SEMANTIC ERRORS 


J SOURCE-LEVEL DEBUGGING TOOLS 


i 
I 


probe 
trace (fecurshve Cau S 


tdinadionds -tieedioeed 4 


[ OBJECT-LEVEL DEBUGGING TOOLS 


(ee OO soe coe, oe oe oe oe | 


debug 

trace stack 

dump segment 

print link info 

print _bind map 

display component _name 


print_linxage usage 
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OTHER PROGRAMMING AND DEBUGGING TOOLS 


I FILE MANIPULATION TOOLS 
io_ call 
print_attach_ table 


close file 


I 

I 

i 

I vfile status 
[ vfile adjust 

IT adjust bit count 
I 


set bit count 


J EXTERNAL REFERENCE MANIPULATION TOOLS 
I resolve linkage error 
Llist_external variables 


delete external variables 


I 
I 
T reset _external variables 
I set _fortran_common 

[ create data_segment 

I 


error table compiler 


IT COBOL RUN UNIT TOOLS 

I run_cobol 

I display _cobol_ run_unit 
I stop _cobol_ run 
I 


cancel cobol program 


te 
t 
OV 
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OTHER PROGRAMMING AND DEBUGGING TOOLS 


RE 


[ GENERAL RUN UNIT COMMANDS 


I 


tr 
4 


run 


stop run 


I SEARCH RULE AND DYNAMIC LINKING TOOLS 


I 
I 
I 
I 
i 


me 


4 


4 


ma ret reLLCUr 


print _search_rules 

add_ search rules 

delete search rules 
ieee = 

hunt 

where 

233 

list_ref names 

initiate 

terminate 


terminate refname 


terminate single refname 
terminate segno lost Enoutedae of lotahon 


MANTPULATION TOOLS 
area status 
create area 
set_user_ storage 
set_system_storage 


list_temp segments 
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SOURCE~-LEVEL DEBUGGING 


B® SOURCE-LEVEL DEBUGGING ALLOWS THE PROGRAMMER TO 


I DISPLAY PROGRAM SOURCE STATEMENTS 
I GIVEN A STATEMENT LABEL 


. GIVEN A LINE NUMBER 


[T DISPLAY THE VALUE OF PROGRAM DATA VARIABLES 


I GIVEN THE NAME OF THE VARIABLE 


[T DISPLAY THE VALUE OF PROGRAM DATA VARIABLES 


I] GIVEN THE STORAGE LOCATION AND DATA FORMAT OF THE VARIABLE 
J DISPLAY THE DECLARATION OF A PROGRAM VARIABLE 


JT DISPLAY THE LIST OF (USER RING) ACTIVE PROGRAMS 
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SOURCE-LEVEL DEBUGGING 


® SOURCE-LEVEL DEBUGGING ALLOWS THE PROGRAMMER TO 


I SET BREAKPOINTS BEFORE OR AFTER STATEMENTS 


[I TO INTERRUPT NORMAL FLOW OF EXECUTION 


ro] 
+3 
© 
tri 
va 
ry 
td 
WO 
90 
QO 
?) 
py 
tJ 
ty 
tJ 
ay 
a) 


STATE OF THE EXECUTING PROGRAM 
I TO CHANGE THE VALUE OF PROGRAM DATA 
[ TO ALTER THE FLOW OF EXECUTION THROUGH THE PROGRAM 


JT TO CONDITIONALLY PERFORM ANY OF THESE FUNCTIONS 


IT ONLY IF A PROGRAM DATA VALUE MEETS SOME CONDITION 


[ REPEATEDLY WHILE A PROGRAM DATA VALUE MEETS SOME CONDITION 
I TRACE CALLS TO A PARTICULAR PROGRAM 


I CALL PROGRAMS WHICH EXPECT NON-CHARACTER ARGUMENTS 
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OBJECT LEVEL DEBUGGING 


S OBJECT-LEVEL DEBUGGING TOOLS ALLOW THE PROGRAMMER TO 


I PERFORM MOST SOURCE-LEVEL DEBUGGING FUNCTIONS, PLUS 


I GIVEN THE STORAGE LOCATION AND DATA FORMAT OF THE VARIABLE 


[T DISPLAY PROGRAM SOURCE STATEMENTS 


I GIVEN A LOCATION IN THE PROGRAM OBJECT SEGMENT 


[I DISPLAY AND CHANGE THE VALUE OF MACHINE INSTRUCTIONS COMPILED TO 
EXECUTE A SOURCE STATEMENT 


IT DISPLAY THE FORMATTED CONTENTS OF 
1 THE PROGRAM ACTIVATION HISTORY SEGMENT (THE STACK) 


{| AREA SEGMENTS 
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OBJECT LEVEL DEBUGGING 


S OBJECT-LEVEL DEBUGGING TOOLS ALLOW THE PROGRAMMER TO 


T DISPLAY AND CHANGE THE CONTENTS OF ANY SEGMENT 
1 GIVEN ITS PATHNAME 
I GIVEN ITS REFERENCE NAME 
[. GIVEN ITS SEGMENT NUMBER 


[ WHEN THE USER HAS ADEQUATE ACCESS TO PERFORM THE REQUESTED 
OPERATION 


T DISPLAY AND CHANGE THE CONTENTS OF HARDWARE REGISTER IMAGES 
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TOPIC: il 


SOURCE LEVEL DEBUGGING - AN INTRODUCTION TO 
DOD COMMAND. Ace. “ec Gere ec Os es cek Ss St, we 
The probe Environment . .... « ° 

A Sample Program. . . « « « « «© e ° 
SCENARIO ONE: FUNDAMENTAL probe . * 
Scenario Two: More probe. .... . 
Breaking Program Execution. ... . 
Scenario three: Simple Break Processing 
Additional Break Control. ..... ° 
Prooe Odds: and “Ends: 6s Gm <a Se Se 
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Toric Il SOURCE-LEVEL DEBUGGING (PROBE) Topic If 


OBJECTIVES: 


Upon completion of this topic, students should be able to: 


1. Use the appropriate PL/1 compiler control arguments to enable 
probe to function on an obJect segment. 


2. Describe the different situations under which probe may be 
invoked. 
3. Debus a Program usins the followings probe resuests: 
source (sc) 
value (¥v} 
symbol (sb) 
auit ¢4} 
hele 
stack (sk) 
4. Maniepulate breakpoints in a Program usins the followings probe 
requests: 
Posilion (eps), status (st) 
before (6b), after (a); reset (Fr) 


continue (cc), continue_to (ct), star (5) 


5. Use the probe builtin functions. 


Multics Ii-1 Fe 


THE PROBE ENVIRONMENT 


FUNCTIONS AS A SUBSYSTEM FOR PROGRAM RECOVERY 


DRIVEN BY INTERACTIVE REQUESTS 
I LONG AND SHORT FORMS AVAILABLE 


J REQUEST DELIMITER IS EITHER NEW LINE OR SEMI-COLON 


WORKS BEST WITH COMPILER GENERATED SYMBOL TABLE 
I CURRENTLY AVAILABLE FOR COBOL, FORTRAN, AND PL/I 
ay NRE ved 


I USE -table option mfr % 


[ MAY ALSO USE -short_ table OPTION 


fies pet ee le ae ee ee Oe gep ite tern We CEG oe our ehh gy 


| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 


r-07247 0.159 43 


pll check back issues -sv2 
PL/I 26a 
r°07443" 34391 “221 


probe check back_issues 
probe: Cannot get statement map for this procedure. 
r 07:48 0.108 31 


pll check_back_issues -sv2 -tb 
PL/I 26a 
r 07:48 3.486 217 


probe check back issues 
Using check back issues (no active frame). ot on STAG 
source ~ ~ 
check back issues: 

_ proc; 
guit 
YO OTseo- O4173 24 
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THE PROBE ENVIRONMENT 


[. MAY BE INVOKED FROM SEVERAL SITUATIONS 
I AFTER AN UNHANDLED CONDITION (READY LEVEL NOT EQUAL TO ONE) 
/ 
[ AT READY LEVEL ONE WITH NO PROGRAM SPECIFIED To C Kaw 8 STACK 


I AT READY LEVEL ONE WITH PROGRAM SPECIFIED 
On Cenve (Sion gna 
IT IMPLICITLY AT A PREVIOUSLY SET BREAKPOINT 


[T MANAGES TWO IMPORTANT PIECES OF INFORMATION 


I SOURCE POINTER 
[ FRAME OF PROGRAM (ONLY IF ACTIVE) 
1 BLOCK OF CODE WITHIN PROGRAM - 
{[ LINE OF CODE WITHIN PROGRAM 


I BASED UPON MANNER OF INVOCATION 


I CONTROL POINTER 
I LAST INSTRUCTION EXECUTED 


BASED UPON MANNER OF INVOCATION 


-m  +'t 


USUALLY AT BREAKPOINT, FAULTING INSTRUCTION, OR FIRST 
INSTRUCTION IN BLOCK 


gs USES A PERMANENT DATA BASE FOR OPERATION 
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THE PROBE ENVIRONMENT 


— 


LOCATED AT >udd>[{user project]>{user name]>[user name].probe 
[ CONTAINS PATH NAMES OF PROGRAMS WITH BREAKPOINTS SET IN THEM 


I IS REFERENCED BY probe WHENEVER 
[T A BREAKPOINT IS ESTABLISHED OR FREED 


IT A BREAKPOINT IS ENCOUNTERED WHILE A PROGRAM IS RUNNING 


J] IF THIS DATA BASE IS DELETED, probe LOOSES INFORMATION ABOUT 
BREAKPOINTS 


1 IF probe COMPLAINS ABOUT A "seg fault" THE DATA BASE MAY BE 
DELETED 


IT probe CANNOT FREE ANY BREAKPOINTS THAT HAVE BEEN PREVIOUSLY 
SET 


[ TO FREE ANY "LOST" BREAKPOINTS, ONE MUST RECOMPILE THE 
AFFECTED PROGRAM 
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A SAMPLE PROGRAM 


8 THE EXAMPLE FOR THIS COURSE 


J IS WRITTEN IN PL/I 


I IS FAIRLY WELL STRUCTURED 


I IS EASY TO READ IF YOU ALREADY KNOW A FORTRAN OR COBOL RELATED 
LANGUAGE 


IT HAS SOME BUGS IN IT 


I WILL BE USED IN THE DEBUGGING SCENARIOS THAT FOLLOW 
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A SAMPLE PROGRAM 


# THE FOLLOWING PROGRAM IS SUPPOSED TO 
[. KEEP TRACK OF BACK ISSUES OF MAGAZINES OF A SMALL COMPANY 


I EACH RECORD CONTAINS THE NUMBER OF ISSUES LEFT IN STOCK, HOW 


MANY ARE REQUESTED FOR SHIPPING, AND THE CURRENT COST OF 
PURCHASE 


[1 PRINT OUT A SUMMARY OF THIS DATA 


I ACCEPT TWO INPUT STRINGS 
I BOTH IN THE FORM OF volume:number 


[ SPECIFY THE FIRST AND LAST ISSUES TO BE SUMMARIZED 


~T PRINT OUT EACH RECORD AND CALCULATE RUNNING TOTALS 
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8 THE 


A SAMPLE PROGRAM 


PROGRAM 


check back issues: 


doi 
del 
ae. 
del 
del 
del 
del 
ael 


Arl 


Neh Wee ci 


dcl 
Jel 


acl 


acl 
aol 
del 
del 


Not To 


proc; 


[BRR RRRRRKRKKERKKR RRR KKKKRAERRKKRRKRKRKRKKRKKRRKE 


* declarations for check back issues * 


* and its subroutines: * 
RRR KKKRK KR KEKE KEKE RK KEK REKEREKEREKRREERER / 


back issues file; 
(first_issue, last_issue) char (12); 
(farec. issue _delim; last issue delim) fixed bin (24); 
index Builtin; , = 
substr builtin; 
number of issues fixed bin; 
issue Fixed bin; 
1 issue record, 

2 current_inventory fixed bin (17), 

2 pending requests fixed bin (17), 

2 cost of issue fixed dec (8,2); 

tal _number_ pending Fixed bin; 

oe number stocked fixed bin; 
total stock value fixed dec (8, 2); 
(current volume, current _humber) fi 
(last_issue_num, first issue num) f 
(sysin, sysprint) file; 7 
(first issue volume, last_issue volume) fixed bin; 
colon internal static options (constant) 

char (1) aligned init (":"); 


open file (back issues) keyed sequential input; 


[RR RRR RR RERE RRR KEKE KR RERRRERKERERKRKERRERKKEEEE 


= get number of the first and last issues - 
the user wants to check. the form is = 
volume:number. this routine will split . 
the components up into issue_ volume * 
and issue number, and positi on to tha * 

*® 

* 


record in the file. 
(eee eee oe eee ee oO eee ee ee eee eee eer e ee eee eee ee ee ee / 


+ + be FF 


put list ("Erom (specify vol:num): "); 
get list (first issue); 

put list ("to (specify vol:num): "); 
get list (last_issue); 
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A SAMPLE PROGRAM 


first_ issue delim = index (first issue, colon); 
last Issue delim = index (last iSsue, colon); 
first issue volume = i 

Substr (first_issue, 1, first_issue delim); 
last_issue volume = 

~substr (last_issue, 1, last_issue delim); 
first issue num = iad = 

Substr_ (first issue, first_issue delim); 
last_issue_num = 

“substr (last_issue, last issue delim); 


call position_ File (first_issue_ volume, 
first issue num); 


number of issues = 
(6*last_ issue_volume + last_issue_num) - 
(6*first_ issue_ volume + first_ issue _num) ; 


do issue = 1 to number of issues; 
call print_record (); 
end; 


call print_summary (); 
close file (back issues); 
return; 

[ RERRKKRKKKKKKRRRKRRKKRKRKKKRKRKKKRRKEE 


m begin support subroutines = 
HRKKKKKKKKKAKRK KKK KEKKKKK KEKE ER / 


print _record: 
proc (); 


[J BRR RRRERKRRERREREKRRKEREREREKEEKEKERKKREKKRKRKRREEK 
* this subroutine obtains the next record * 


* trom the back issues file, calculates * 
* some totals, and outputs the current 
* record in a formatted form. * 


RRKRKKAKKKKK KKK RKRRKKKKRHAKKKEKRKKKKKRRKEEKKEKEKEEE / 


call get_record (); 


total number pending = 

total_ number pending + 

issue record. pe doce requests; 
total number stocked = 

total number stocked + 

issue record.current _inventory; 
total_ stock “value= 
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A SAMPLE PROGRAM 


total stock_ value + 
(issue_ record.current _inventory* 
issue_ record. cost_ of . issue); 


put skip edit ("volume", 

current volume, 

"number™, 

Serer haa 
"stocked: 

issue record. current inventory, 
"outstanding requests:", 

issue record.pending = PeGueS res 
"cost of this issue:" 

issue _record.cost_ OF. issue, 


(r (output _format_1)) 
file (sysprint); 


return; 


output format 1: 


format. (ao): Cl) ~ £13,0)— 2th), 
al(Ojy Sti) £(3,0)/, Skim (l)yy (11), 
a(8), x(1), £(6,0), x{1), 
at2i) ¢ Si) ¢  £(6,0)7- x01), 
a(l9), x(1), p"$$$,$39v.99", afl)}; 


end print record; 


position file: 
proc (first_vol, first num); 


[BERR RR EKER RRR ER EK RK EER EER KER ERE RRR REKE REE 
- this subroutine positions the back issues * 
file to the record specified by the * 
first issue specifier given by the user = 
at the beginning of the program. to = 
position to the record, we simply read * 
records we don't want and do nothing with sg 
* 

x 


them. 
RAK KKK KK KKK KKK KERR ERK KK REERERKEREKR KEK RRAKERERE / 


+t + + OF a Ft 


del (first_vol, first _num) fixed bin; 


do while (£irst_ vol, > current _volume); 
call get_ récord ‘ee 
end; 


do while (first num > curr ent number) ; 


call get record (); 
end; 
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A SAMPLE PROGRAM 


return; 
end position file; 
get record: proc (j; 


dcl key char (8); 


[BR RRRRREREKRKRERKERERKRKRKRRRREKRRRKRKKRKRRRKERKEKRRKRRREKK 


* this subroutine reads a record from the - 
back issue file into the issue record. = 
the other necessary information, vol * 
and num of the issue, was stored in al 
the record's key. we must extract this * 
from our internaliy declared key and * 
place it in the globally available bd 

* 

* 


current volume and current number vars 
KH RK KKK KERR KKK RRR KER RRR RRR RRRRER y- 


+ e+ t+ + + HF 


read file (back_issues) 
into (issue record) 
Keyto (key); 


current volume = substr (key, 1, 4 
current number = substr (key, 5, 4 


return; 


end get record; 


print summary: 


proc (); 

[RRRRKRRKEKKRKKRKKK KK RRR KKK KKK 
* a simple subroutine, all this * 
* does is print out the totals * 
- calculated by the print record * 
* subroutine. = * 


RAK KKRKKKEKK ERK RRR RKKRKKKEKKKKERK EEE / 


put skip (2) 
edit ("number of issues stocked:", 
total number stocked, 
"number of requests pending:", 
total number pending, 
"total stock value:", 
total stock value, 
W 6 
(r (output format 2)) 
file (sysprint); — 


Not To Be Reproduced 2-9 Fe2k 


A SAMPLE PROGRAM 


output format 2: 
Format (a(25), x(1), £(6,0), skip (1), 
a(27), x(1), £(6,0), skip (1), 
a(i8), x(1), p"$$$,S$$9v.99", a(1)); 
end print summary; 


end check back issues; 
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SCENARIO ONE: FUNDAMENTAL PROBE 


@ SOME PRIMARY probe REQUESTS 


eo SN 


I THE source REQUEST 


wm” 


[T PRINTS SOURCE STATEMENTS 


m4 
CG 
YW) 
Wo) 
Q) 
tj 


sc 
Source <number of lines> 


sce <number of lines> 


- I EXAMPLES: 
Source 7 


sc 3 


I THE value REQUEST 


I DISPLAYS THE VALUE OF A SINGLE VARIABLE, AN EXPRESSION, OR 
SECTION OF AN ARRAY 


. USAGE: 
value <expression> 
v <expression> 
value <array cross sectionm> 


v <array cross section> 
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SCENARIO ONE: FUNDAMENTAL PROBE 


I EXAMPLES: 
value x 
value array (1:5) 
value stri.mem2.elem 
v ptrl -> some _based_var 


vy ptr2 -> really big.meml.comp (2).z 


I SPECIFYING THE EXPRESSION FOR THE value REQUEST 


[ MADE FROM PROGRAM VARIABLES, CONSTANT VALUES AND probe 
DEFINED FUNCTIONS 


IT PROGRAM VARIABLES MUST APPEAR EXACTLY AS THEY WERE TYPED 
IN YOUR PROGRAM 


loop counter (PL/T) 


data-part (COBOL) 
I CONSTANTS SHOULD BE IN A FORM ACCEPTABLE TO YOUR PROGRAM 


=oo 


'STRING' 


I probe MAINTAINS A SET OF BUILTIN FUNCTIONS THAT RETURN 
VALUES TO YOU 


addr —- RETURNS THE ADDRESS OF ITS ARGUMENT 


addrel - RETURNS AN ADDRESS RELATIVE TO THE SPECIFICATION 
OF ITS ARGUMENTS 


baseptr - RETURNS THE ADDRESS OF THE BEGINNING OF A 
SEGMENT 


length - RETURNS THE LENGTH OF A BIT OR CHARACTER STRING 
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SCENARIO ONE: FUNDAMENTAL PROBE 


maxlength - RETURNS THE MAXIMUM ALLOWED LENGTH OF A STRING 
null = RETURNS A SPECIAL INVALID ADDRESS | 

octal ~ RETURNS THE MACHINE REPRESENTATION OF ITS ARGUMENT 
pointer - RETURNS AN ADDRESS BASED UPON ITS ARGUMENTS 


rel - RETURNS THE ADDRESS WITHIN A SEGMENT INTO WHICH ITS 
ARGUMENT POINTS 


segno - RETURNS THE NUMBER OF THE SEGMENT INTO WHICH ITS 
ARGUMENT POINTS 


substr = RETURNS A PORTION OF A CHARACTER OR BIT STRING 


unspec - RETURNS THE BINARY REPRESENTATION OF ITS ARGUMENT 


I AN EXPRESSION CAN CONTAIN OPERATORS 
1 FOUR DEFINED WITHIN PROBE 
ADDITION - USE A PLUS SIGN (+) 
SUBTRACTION - USE A MINUS SIGN (-) 
MULTIPLICATION - USE AN ASTERISK (*) 
DIVISION - USE A SLASH (/) 


] ORDER IS MULTIPLICATION AND DIVISION, THEN ADDITION AND 
SUBTRACTION 


I ORDER MAY BE OVERRIDDEN WITH PARENTHESES 
I THE symbol REQUEST 
I SHOWS YOU THE DATA TYPE OF A PROGRAM VARIABLE 


J USAGE: 
symbol <name of variable> 


sb <name of variable> 
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SCENARIO ONE: FUNDAMENTAL PROBE 


I EXAMPLES: 


symbol x 


sb HYPTN 


I THE quit REQUEST 


I CAUSES YOU TO LEAVE PROBE 


[ USED TO GET BACK TO COMMAND LEVEL 


I USAGE: 


quit 


g 


@ THE SCENARIO 


I THE PROGRAM BLOWS UP 


I PROBE IS USED TO ASSESS THE DAMAGE 
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SCENARIO ONE: FUNDAMENTAL PROBE 


r 12254 0,155. 21 
check back_issues 


from (specify vol:num):1:1 
to (specify vol:num):2:1 


Error: conversion condition by >udd>MEDmult>F21>doodle>bad_ 
\ecbiScheck back issues|540 (line 48) 

onsource = “1l:", onchar = ":" 

Invalid character follows a numeric field. 

system handler for error returns to command level 

r 12:54 0.273. 52 level 2 


probe 
Condition conversion raised at line 48 of check back _ issues 
\e(level 7). 


source 
First issue volume = 
substr (first_issue, 1, first_issue delim); 


ee ete ene eer a NY mm ee iy eee em mn eh ee ee ee 


value first issue delim ; 
first issue delim =2 


value first issue 
fFirst_issue ="1:1 y 


value substr (first_issue, 1, first issue delim); 
wyen = = 


symbol first_issue_ volume 
fixed bin (17) automatic 
Declared in check_back issues 
v substr (first issue, 1, first issue delim - 1); 
iy 18 — as = 
q 
r 07:03 0.591 210 level 2 


CL 
r 07:03 0.045 9 


mmr ee ee eee mura core meee ent erm ee em es NT A me ER OR ce SD ee pe ET ON RR RAY (ON REN SRS ome SND Souenet <A mum SONI? wrny, 


eae eet cen ere meme eee ees ny ee emote ey Se ey i mene SM ie cre tee + 
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SCENARIO ONE: FUNDAMENTAL PROBE 


I TECHNIQUE 
IT INVOKE probe - IT TELLS YOU WHAT HAPPENED 
I FIND THE STATEMENT AT WHICH THE PROGRAM DIED 


[ CHECK ALL THE VARIABLES IN THAT STATEMENT 
I NOTE THE IMPLICIT CONVERSION 


I THE SUBSTR BUILTIN WAS THE CULPRIT 


= YOUR TURN 


I WHAT WAS THE PROGRAMMER TRYING TO DO WITH THE SUBSTRING BUILTIN? 


T HOW WOULD YOU CHANGE THE PROGRAM SO THAT THE IMPLICIT CONVERSION 
SUCCEEDS? 14 e 
Eyre os See dal  d 


] ARE THERE ANY OTHER STATEMENTS WHERE THIS CONDITION MAY HAPPEN? 
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SCENARIO TWO: MORE PROBE 


@ AS ERRORS ARE FOUND THEY ARE FIXED 


I MODIFY THE SOURCE ONLY 


I RECOMPILE INTO NEW OBJECT 


I CLEAN UP ANY FILES THAT MAY HAVE BEEN LEFT INCONSISTENT 


Ue Ree Re ee eee ONG Sere aly 


qedx 
rcheck_back issues.pll 
48 
first issue volume = 
etl = > 

substr (first_issue, 1, first_issue delim); 
s/)/ - 1)/p 

substr {£Irst issue, ly -Eivse issue delin =o 1 
a 
g 
r 07:55 0.549 88 
pil check_back_issues -tb ~sv2 
PL/I 26a 
r.07<55. 3.317 383 


r07<553° 0.049 8 


close file back_issues 
r 07:58 0.082 23 


sy ee were ae nes eens eee ee ees em ee De een eee 


| 
| 
| 
| 
| 
| 
| 
| 
)d 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 


3 RUN THE NEW PROGRAM 


I BE AWARE OF NEW PROBLEMS 
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SCENARIO TWO: MORE PROBE 


] MAKE SURE THE OLD PROBLEM IS FIXED 


I LOOK FOR ANY EFFECTS YOUR CHANGE MAY HAVE ON OTHER PORTIONS OF 
THE PROGRAM 


Be ra ee ee ee SE Age ewe ee cen we remem Orr p pare gerres AeEa eS 
check back issues 


From (specify vol:num):1:1 
to (specify vol:num):1:4 


Error: conversion condition by >user_dir_dir>MEDmult>F21>do 


\codle>bad_cbiScheck back _issues/551 (line 50) 
onsource = "1:", onchar = “:;" 
Invalid character follows a numeric field. 
system handler for error returns to command level 
r 07:58 0.367 34 level 2 
probe 
Condition conversion raised at line 50 of check back issues 
\c (level 7). 
source 

last_issue_ volume = 

substr (last_issue, 1, last_issue delim); 

From Pandolf.MEDmult 05/19/81 0759.5 mst Tue: 
The handbooks came in today. I have them if you want to see 
\ethem. 
sm Pandolf.MEDmult good, be there later 
probe: Unknown request. “sm” 


nce chemin NAONOIN fatten tnt cin ey A ke mite amet “armen fm RS nalts seme Mme 


® SOME INVALUABLE REQUESTS 


I THE list requests REQUEST 
I LISTS ALL THE ALLOWED REQUESTS IN probe 


I USAGE: 
list_requests 
Pq 
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SCENARIO TWO: MORE PROBE 


Summary of probe requests: 


after, a 

args 

before, b 
call.,-¢l 
continue, ¢ 
continue to, ct 


declare, dcl 
display, ds 
execute, e 


goto, g 
halt, h 
help 

Le 


input_switch, isw 
language, lng 

let, 1 

list help, ih 

list builtins, lb 
list requests, lr 
List variables, Isv 


modes, mode 

output switch, osw 
pause, Pp 

position, ps 


quit, q 


reset, x 
source, 
stack, 

status, 
step, s 
symbol, sb 


sc 
Sk 
st 


use 
value, v 
where, wh 


while, wl 


Type "help" for more 
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Set a breakpoint after the specified statement. 
Print argument list for procedure. 
Set a breakpoint before the specified 
Call a subroutine. 

Continue after a breakpoint. 


Resume execution from last breakpoint and stop 
at specified statement. 

Create a probe variable. 

Display storage in various formats. 

Execute a Multics command line, usually 
within a break request. 

Continue execution at a specified statement. 

Halt ands re-enter probe. 

Print info files for probe requests. 

Execute probe requests based on specified 
condition. 

Set the I/0 switch used for probe input. 

Display or set the current language. 

Change the value of a variable. 

List the available info topics for probe. 

Print a summary listing of all probe builtins. 

Print a summary listing of the vrobe requests. 

Print type and value of one or more probe 
variables. 

Set probe operation modes. 

Set the I/O switch used for probe output. 

Reset the current breakpoint and halt. 

Move the probe pointer to a new location 
and display the source. 

Leave probe and return to Multics command 
level. 

Reset breakpoints. 

Display source of program. 

Display the stack. 

Display the status of breakpoints. 

Execute one statement and halt. 

Display information about the specified 
symbol. 

Move the probe pointer to a new location. 

Print the value of a variable or expression. 

Display the current values of the probe 
pointers. 

Execute probe requests while condition 
is true. 


information. 


Statement. 


ed 


SCENARIO TWO: MORE PROBE 


I THE help REQUEST 


I USAGE: 
help 
help <request> 


help <feature> 


I EXAMPLES: 
help 
help quit 


help EXPRESSIONS 


| THE execute REQUEST 
I ALLOWS A MULTICS COMMAND TO BE PROCESSED WHILE STILL IN probe 


[ USAGE: 
execute <command line> 


e <command line> 


IT EXAMPLES: 
execute "pwd" 


e “iss *.pll" 
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SCENARIO TWO: MORE PROBE 


I USING THESE REQUESTS 
pe te ee eee ree See ee ee tee ee re ee 


help execute 
09/27/79 The "execute" request. 


Syntax: execute STRING 


| 
| 
| 
| 
| 
| 
The contents of STRING are passed to the Multics command pro | 
\ecessor. | 
This request is chiefly useful in break request list, because| 
\ce the more | 
convenient escape to the Multics command processor is not av | 
\cailable | 
then. | 
| 

The user can pass an arbitrary line to the Multics command p | 
\crocessor | 
by preceeding it with ".." on a new line. | 
| 

| 

| 

| 

| 

| 

| 


Examples (6 lines). More help?no 

execute sm Pandolf.MEDmult good, be there later 

probe (execute): The Multics command lines must be enclosed 
\cin quotes. ; 

e "sm Pandolf.MEDmult good, be there later" 


en vO nn Oe ene nmuaiianammaiiamanslinemendtiommnd 
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SCENARIO TWO: MORE PROBE 


[ FINISHING UP THE CURRENT ERROR 


source 
last_issue volume = 
substr (last_issue, 1, last_issue delim); 

value substr (last_issue, 1, last_issue delim) 

i ea 
sb last issue volume 

fixed bin (17) automatic 
Declared in check back issues 
quit as 

r 08:10 2.508 492 level 2 


gedx 
rcheck back issues.pll 
56,515" = 
iast_issue volume = 
ert 

substr (last_issue, 1, last_issue_ delim); 
$/)/ ~- 1)/p 

substr (last_issue, 1, last_issue delim - 1); 
52,550 


first issue num = 
Substr (first issue, first issue delim); 
last issue num = ~ 1 ; 
“substr (last_issue, last_issue_delim); 
535/17 +. LY/o 


substr (first issue, first _issue delim + i); 
55s/)/ + 1)/p 


substr (last_issue, last issue delim + 1); 


QO = 


r 08:12 0.423 80 level 2 


pli check back issues -sv2 -tb 
PL/I 26a 
r 08:13 3.524 141 level 2 


rl 
r 08:15 0.046 29 


e file back issues 


clos _£ = 
y 08:15 0.05121 


re em ee me er es mm em te ents clint tanh erm term RS nt eR cette ce ete i Se ee ND ee 
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SCENARIO TWO: MORE PROBE 


@ ADDITIONAL USE OF FUNDAMENTAL PROBE REQUESTS 


J SOME USEFUL INFORMATION ABOUT A FAILURE WILL COME INDIRECTLY 
FROM THE probe DIALOGUE 


J NOTE THE USE OF value IN THE NEXT WINDOW 
ae wR ee ee te eee ore ante ects SP we ete ars a ere e ae Surg ee gm e eit 
check_back_ issues 


From (specify vol:num):1:1 
to (specify vol:num):1:4 


Error: illegal procedure condition by >user dir dir>MEDmult 
\c>F21>doodle>bad_ cbi$print record|575 (line 98) 

(while in pll operator real” Oo. real. tr) 

referencing stack 4/6503 (in process air) 


c 08:15 0.369 42 level 2 


| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| pb 
| Condition illegal procedure raised at line 98 of print_recor 
| \ed (level 8). 

| se 

| total stock value = 

total Stock value + 

| (issue_ record.current inventory* 
| issue record. cost of Issue); 

| v issue record.cost OE. issue 

| cost_of issue = 5 

| v issue_ record. CuLrene inventory 

| current _ inventory = 23 

| v total stock value 

| total stock value = (invalid decimal data) 

| symbol total stock value 

| fixed dec (8,2) automatic 

| Declared in check back issues 

| value octal (total_stock_value) 

| ie iu dose aca 

| vr 08:19 0.234 33 level 2 

| 


EL 
er 08% 19 6,037 22 


ee ee eee en et ere ee ee ey ie Se Sa ee ee Se eee mney SO ee sme mimes mR SY emmene 
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SCENARIO TWO: MORE PROBE 


ee ee en een Ne ere ce 


gedx 

rcheck back issues.pll 

/del total stock value/ 

del total_stock value fixed dec (8,2); 

s/;/ init (0)3/p 

del total_stock value fixed dec (8,2) init (0); 
W 


q 
.© 08:20 0.207 24 


pll check back_issues -sv2 <-tb 
PL/I 26a 
C0622) 3.46). 233 


close file back_issues 
r 08:22 0.107 69 


ents See Re eee eee ene cn eee ce ee et NE MO me ee 


bmnd 


THE illegal procedure CONDITION ITSELF EXPLAINED LITTLE ABOUT 
THE ERROR 


THE PL/I STATEMENT WAS TOO COMPLEX TO QUICKLY DETERMINE THE 
IMMEDIATE CAUSE | 


tt 


I THE value REQUEST UNCOVERED THE FACT THAT ONE VARIABLE HAD 
INVALID DATA 


I BECAUSE OF THIS THE VALUE OF total stock value WAS 
UN PRINTABLE 


I THE octal BUILTIN FUNCTION ALLOWED US TO LOOK AT THE DATA 
THAT WAS THERE REGARDLESS OF THE DATA TYPE 


IT THE PRESENCE OF SPACES (OCTAL 040) INDICATED THAT THE 
VARIABLE WAS NEVER INTIALIZED (TO OCTAL 050) 
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BREAKING PROGRAM EXECUTION 


@ BREAKPOINTS 


[ AT TIMES, THE PROGRAMMER DESIRES TO VIEW INTERMEDIATE PROGRAM 
VALUES 


J ONE OPTION IS TO PLACE I/O STATEMENTS IN THE SOURCE PROGRAM 
I COSTS TOO MUCH IN TERMS OF RECOMPILES 


I STILL PROVIDES NO WAY TO SUSPEND THE PROGRAM 


[ LET THE DEBUGGER DO IT 
IT RECOMPILING NOT NECESSARY TO CHANGE DEBUGGING BEHAVIOR 


IT THE PROGRAM MAY BE SUSPENDED OR CONTINUE ON AFTER PRINTING 
OUT SOME DIAGNOSTIC 


@ PROBE IMPLEMENTATION 


I REVOLVES AROUND THE "BREAKPOINT" 


I A LIST OF ONE OR MORE probe REQUESTS TO BE PERFORMED WHEN A 
STATEMENT IS REACHED 


[T LIKE A SMALL PROGRAM FOR EACH STATEMENT 


I MODIFIABLE AT WILL BY THE PROGRAMMER 


I probe BREAKPOINTS CAN BE SPECIFIED TO BE EXECUTED EITHER BEFORE 
OR AFTER AN EXECUTABLE STATEMENT 
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BREAKING PROGRAM EXECUTION 


[ BEFORES AND AFTERS ARE SEPARATE BREAKS, AND BOTH WILL BS 
EXECUTED IF ENCOUNTERED CONSECUTIVELY 


I COBOL COMPILER RESTRICTIONS LIMIT COBOL PROGRAMS TO THE USE 
OF BREAKPOINTS BEFORE THE STATEMENT ONLY 


@ BREAKPOINT REQUESTS 


[ THE before REQUEST 


[T USAGE: 
before <line> 
b <line> 
before <line>: (<request list>) 


b <line>: (<request list >) 


T EXAMPLES: 
before 


before 30 


(Setore 5: (value x; value y) 


~~, — 


before: value comp-val 


{ NOTES: 


I IF NO LINE NUMBER IS SPECIFIED, THE CURRENT LINE IS 
ASSUMED 


I IF ONLY ONE REQUEST IS DESIRED AT THE BREAK, THEN THE 
PARENTHESES MAY BE OMITTED 


[. IF NO REQUEST IS SPECIFIED, THEN A "halt" REQUEST IS 


ASSUMED, CAUSING THE PROGRAM TO STOP AND PROBE TO BE 
ENTERED 
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BREAKING PROGRAM EXECUTION 


IT THE stack REQUEST 
I NOT SPECIFICALLY A BREAK REQUEST 
I DISPLAYS LIST OF ALL PROGRAMS THAT HAVE NOT FINISHED YET 
I ALLOWS YOU TO SEE HOW oan YOUR PROGRAM HAS am 
[ SHOWS RELATIONSHIPS BETWEEN PROGRAMS 
IT MORE ON STACKS LATER 


I USAGE: 
stack 
sk 
stack <amount> 
sk <amount> 
stack <first frame, amount> 


sk <first frame, amount> 


IT EXAMPLES: 
sk 
stack 4 
sk 12,3 


I THE position REQUEST 


IT POSITIONS TO AND PRINTS A SPECIFIED SOURCE STATEMENT 
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BREAKING PROGRAM EXECUTION 


I USAGE: 
position <label> 
ps <+,-line> 
ps <line> 


ps <"string"™> 


I EXAMPLES: 
position do_label 
ps +3 
ps -4 


ps 68 
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SCENARIO THREE 


® LET'S RETURN TO OUR EXAMPLE 


SIMPLE BREAK PROCESSING 


check_back_ issues 


from (specify vol:num):1 
to (specify vol 


volume 1 number 1 


smum):1:4 


stocked: 23 outstanding requests: 


\c of this issue: 
$5. 00% 
volume 1 number 2 


Stocked: 30 outstanding requests: 


$3.00. 
volume 1 number 3 


stocked: 27 outstanding requests: 


\e of this issue: 
$3.00. 


Error: size condition by >user dir dir>VEDmult>F21>doodle>b 


\cad _coisprint_ summary|i255 (line 193) 


Precision of target insufficient for numser of integral digi 


\cts assigned to it. 


system handler for error returns to comm:nd Seve. 


| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| \c ef this issue: 
| 

| 

| 

| 

| 

| 

| 

| rc 08:23 0.420 40 level 2 
| 
| 
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SCENARIO THREE: oe BREAK PROCESSING 


probe 
Condition size raised at line 193 of print summary (level 8). 
source a 
put skip (2) 
edit ("number of issues stocked:", 
total number stocked, 
"number of requests pending:" 
total number pending, 
"total stock value:", 
total _ stock value, 
" oo) 
(r (output format 2)) 
file (sysprint); 
stack 
LS simple_command_processor|12265 
14 command processor_ 111070 
13 abbrev_ [5336 
12 release stack/10031 
pe unclaimed _signal|27064 
10 wall|4436_ 
) wall| 4407 ; error 
8 print _Summary (line 193) size 
7 check back issues (line 70) an 
6 simple_ command _processor|12265 
> command processor_ {21070 
A abbrev_175336 
3 Listen_ 110031 
Z project_ start_up [41747 
Ba user_init_admin_ 142452 (alm) 
sc 


put skip (2) 
edit ("number of issues stocked:", 
total number stocked, 
"number of requests pending:", 
total number pending, 
"total stock value:", 
total stock value, 
” Ps 
) 
(r (output format_2) ) 
file (sysprint); 
v total number stocked 
total number stocked = 4,.30337¢e9 
position "total _humber stocked =" 
total number stocked = 
total number stocked + 
issue record. current inventory; 
before we ~ 
Break set before line $5 
Gure 
r 08:27 0.968 317 level 2 


ecm me ewer en eee em ma ge a ee eee meee ec ete mem anime me te eet cet a et ie ee ee tlt erento SU ne ee es nn eee i a me es ee 
iis’ «Thin! ‘isa sai Ske i ~ ei) Simin Y “Som cy cea cs, amie pitino “eats erat, Seca’ Sara. ys at” tne lei ine ice spams “sii = esi cere Manone deem reine prwene anacmettMNN® gyeumy aameine eubewn TUD ccc emia a ect meee " ae, - 
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SCENARIO THREE: SIMPLE BREAK PROCESSING 


I THE PROGRAM WILL NOW STOP BEFORE LINE 95 IS REACHED 
I probe IS AUTOMATICALLY INVOKED 


I THE REQUEST LIST IS PROCESSED 
I IN THIS CASE, WE ARE PLACED AT probe REQUEST LEVEL 


I IF THE halt REQUEST WAS NEITHER IMPLICITLY NOR EXPLICITLY 
STATED, EXECUTION WOULD CONTINUE WITH LINE 95 


cl 
r 08:27 0.041 19 


close file back_issues 
r 08:28 0.049 17 


check back issues 


from (specify vol:num):1:1 
to (specify vol:num):1:4 
Stopped before line 95 of print_record. (level 8) 
source 
total _ number stocked = 
total number stocked + 
issue record.current inventory; 
v total number stocked a 
total number stocked = 4.30337e9 
symbol total number stocked 
fixed bin (17) automatic 
Declared in check back issues 


wee eee eee meet ee eee ee ene ce en cee SN re me es ce 


q 
e-08230' 0.441 115 


i ene en nn ee iin ediliceestlicnentnenanetiinnnentitinienedidi peewee een 


[ TECHNIQUE: 
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SCENARIO THREE: SIMPLE BREAK PROCESSING 
IT NOTE THE CONDITION: size 
J RESULT TOO BIG TO BE PLACED IN TARGET STORAGE LOCATION 


[T DISAGREES WITH THE WAY THE PROGRAMMER THOUGHT TO USE IT 


1 FIND OUT WHERE THE VARIABLE IS ASSIGNED 
IT SET BREAKPOINT THERE 


IT LOOK AT VALUE OF VARIABLE AT THAT STATEMENT 


IT THE VARIABLE HAD A RANDOM VALUE IN IT 
J] IT WAS NOT INITIALLY SET 


J THIS CARRIED THROUGH UNTIL IT BLEW UP AT THE OUTPUT 
FORMATTING 
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SCENARIO THREE: SIMPLE BREAK PROCESSING 


gedx 

rcheck back issues.pll 

/del total number _Stocked/ 

deci total_ number _ Stocked fixed bin; 

s/;/ init (0);/p 

del coca bance eee fixed bin init (0); 
W 


q 
F.08:230:-0..256 «30 


pll check back issues -sv2 -tb 
PL/I 26a 
tr O6s351: 34549--1i1 


close file back issues 
r 08:31 0.057 8 


check back issues 


from (specify vol:num):1:1 
to (specify vol:num):1:4 


volume 1 number 1 
stocked: 23 outstanding requests: 0 cost of 
this issue: 
$5.00. volume 1 number 2 
Stocked: 30 outstanding requests: 2 cost of 
this issue: 
$3.00. volume 1 number 3 
stocked: 27 outstanding requests: 0 cost of 
this issue: . . 
$3.00. Error: size condition by 
>user dir dir>MEDmult>F21>doodle>bad_ cbiS$print_summary|1304 
(line 193) Precision of target insufficient for number of 
integral digits assigned to it. system handler for error 
returns to command level 
r 08:32 0.467 22 level 2 


| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 


Not 
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SCENARIO THREE: SIMPLE BREAK PROCESSING 


@ YOUR TURN 


IT THIS LOOKS LIKE THE SAME ERROR. IS IT? HOW DO YOU KNOW? 


| LIST THE STEPS YOU WOULD TAKE TO RESOLVE THIS ERROR. 
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SCENARIO AEBEE: SIMPLE BREAK PROCESSING 


ee 


| 

pb | 

Condition size raised at line 193 of print summary (level —) 
s¢ 

put skip (2) | 

edit ("number of issues stocked:", | 

total_number_stocked, | 

"number of requests pending:" | 

total number —pend ing, | 

"total stock value:" | 

total_stock_ value, | 

on ) | 

(r (output _format_2)) | 

file (sysprint); | 

v total number stocked | 

total number stocked = 80 | 

v total_number_ pending | 

total number pending = 4.30337e9 | 

v total stock value | 

total stock value = 286 | 

sb total number pending | 

fixed bin (17) automatic | ks 

Declared in check _back_issues | 

q | 

r 08:33 0.386 79 level 2 | 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 


qx 
rcheck back issues.pll 

/dcl total number Pending / 

del total number _pending Fixed bin; 

s/;/ init (0);/p- 

dcl total _number_pending fixed bin init (0); 
W 


q 
r 08:34 0.216 35 level 2 


pll check _back_issues -tb -sv2 


PL/I 26a 
r 08:34 3.462 219 level 2 


ri 
r 08:34 0.040 6 


close file back _ issues 
r 08:35 0.042 7 


a “ veces eee cm eee mee anemia earns SOT cena Sin ean fee ee ee TNS SS em Ye ee eet EN mS SY _ 
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ADDITIONAL BREAK CONTROL 


& MORE REQUESTS 


I] THE after REQUEST 


I SETS UP A BREAKPOINT AFTER A GIVEN STATEMENT IN A PROGRAM 
[ OPERATES EXACTLY LIKE THE before REQUEST 


IT USAGE: 
after 
a 
after <line>: (<request list>) 


a <line>: (<request list>) 


IT EXAMPLES: 
after 
after 100 


a 50: (value x; value y) 


I THE status REQUEST 


[ LISTS BREAKPOINTS YOU HAVE SET IN YOUR PROGRAMS 
IT USAGE: 
status 
st 
status <program name> 
st <program name> 


status <line in current program> 
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st <line in current program> 
status -all 

st -all 

status * 


st * 


EXAMPLES: 


— 


status 
Status at 50 
status other-prog 


status -all 


. NOTES: 
“status -all" LISTS ALL BREAKS SET 
"status *" LISTS THE NAMES OF PROGRAMS WITH BREAKS SET 


AN OPTIONAL CONTROL ARGUMENT OF “-long" IS ALLOWED, WHICH 
PRINTS THE PROBE REQUEST LIST ASSOCIATED WITH THE BREAKPOINT 


I THE continue REQUEST 


I ALLOWS THE PROGRAMMER TO RESUME THE PROGRAM AFTER A BREAK 
THAT INVOKED probe 


T USAGE: 
continue 


Cc 


T EXAMPLES: 
continue 


Cc 
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ADDITIONAL BREAK CONTROL 


BACK TO THE SCENARIO 


pe ee ee ee ee 


| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 


check_back issues 


from (specify vol:num):1:1 
to (specify vol:num):1:4 


volume 1 number 1 


stocked: 23 outstanding requests: 
92«00% 
volume 1 number 2 
stocked: 30 outstanding requests: 
S34 00' 
volume 1 number 3 
stocked: 27 outstanding requests: 
$3.00. 
number of issues stocked: 80 
number of requests pending: 2 
total stock value: $286.00: 


cr 08236 0.264 7 


0. C8St of “Enis 


2 Cost of Vthis 


0 cost of this 


I A NEW PROBLEM: NOT ENOUGH RECORDS PRINTED OUT 


issue: 


issue: 


issue: 


I WITH NO CONDITION SIGNALLED, BREAKPOINTS ARE THE ONLY WAY TO 


GET INTO PROBE WHILE THE PROGRAM IS 


RUNNING 


I WITHOUT SETTING TOO MANY BREAKS, ATTEMPT TO STOP THE PROGRAM 


AT APPROPRIATE PLACES AND LOOK AT 
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ADDITIONAL BREAK CONTROL 


probe check back issues 
Using check back_ issues (no active frame). 
ps "do issue" 
do issue = 1 to number of issues; 
b 
Break set before line 66 
quit 
yr 08:39 0.342 137 


check back issues 
E~rom (specify vol:num):1:1 


to (specify vol:num):1:4 
Stopped before line 66 of check back issues. (level 7) 


v number of issues 
number of issues = 3 


{ 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| ps "number of issues =" 
| Mumber of issues = 
| (6*last_ issue volume + last _issue_num) - 
(6*first_issue_ volume + first_issue_num); 
| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 


v last issue volume 
last issue volume = 1 


v last issue num 
last issue num = 4 


Vv first issue volume ;: v first issue num 


Fd 
first issue_ volume = 1 
first. issue_ num = 1 


position +2 
call print_record (); 


after 
Break set after line 67 


continue 


comin er ee crm eee I NS RRND Laken cen eRe SE SS Sl NTN RSME yes NSN SMES ENED memeey SONOMA SUR ce SA nN A cane semen SE meetED SS NORE NY SET SOOO eee am 
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volume 1 number 1 
stocked: 23 outstanding requests: 0 cost 
$5.00.Stopped after line 67 of check back issues. 
v issue = = 
issue = l 
os 


volume 1 number 2 
stocked: 30 outstanding requests: 2 cost 
$3.00.Stopped after line 67 of check_back issues. 
v issue 


issue = 2 
¢ 


volume 1 number 3 
stocked: 27 outstanding requests: 0 cost 
$3.00.Stopped after line 67 of check back_issues. 
v issue 
issue = 3 
status 
Break exists after line 67 in check _back_issues 
Break exists before line 66 in check back issues 
c 


number of issues stocked: 80 
number of requests pending: 2 
total stock value: $286.00.. 
rO8346 1.185: 380 


I TECHNIQUE: 


J IDENTIFY THE LOOP THAT PRINTS THE RECORDS 


4 
Ww 
ie 
- 
» 


I LOCATE THE STATEMENT AT WHICH THE LOOP VARIABLE 


INCORRECTLY SET . 


Il FIX THE SOURCE 
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of this issue: 


(level 7) 


of this issue: 


(level 7) 


BREAK WITHIN THE LOOP AND CHECK THE LOOP 


VARTABLE 


WAS 


cane) Cneien ena apeeen ovens einerets Shami wrineege GOR! namie ie een eee 


Bad 


ADDITIONAL BREAK CONTROL 


GE en ee a ee ee Se ee Eg Ge ge om ee A RO Te 


gedx 

rcueck back issues.pll 
/number of Issues/ 

del number of issues fixed bin; 


Tf 
number of issues = 
s/$/ 1 +/p 
number_of issues = 1+ 
W 
q 
r 09:09 0.270 80 


pil check_back_ issues -sv2 -tb 
PL/I 26a 
cr 09210 3.668 234 


check back issues 
from (specify vol:num): 1:1 


to (specify vol:num):1:4 


‘volume 1 number z 


stocked: 23 outstanding requests: 0 cost 
\cof this issue: 
S500 
volume 1 number 2 
stocked: 30 outstanding requests: 2 cost 
\cof this issue: 
93.00% 
volume 1 number 3 
stocked: 27 outstanding requests: 0 cost 
\cof this issue: 
9300. 
volume 1 number 4 
stocked: 20 outstanding requests: 1 cost 
\cof this issue: 
53.00. 
number of issues stocked: 100 
number of requests pending: 3 
total stock value: $346.00. 


| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
i 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
bP 09210 04362728 
| 

| 
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ADDITIONAL BREAK CONTROL 


] LOOKS GOOD; NOW TEST IT WITH DIFFERENT DATA. 


check back issues 


from (specify vol:num): 2:1 


to (specify vol:num):3:1 


| | 
| 
| | 
| | 
| | 
| | 
| volume l number 1 | 
| stocked: 23 outstanding requests: cost of this issue: | 
| 35.00% | 
| volume 1 number 2 | 
| stocked: 30 outstanding requests: cost of this issue: | 
| 53.00. | 
| volume 1 number 3 | 
stocked: 27 outstanding requests: cost of this issue: | 
| 346 UCs | 
| volume 1 number 4 | 
| stocked: 20 outstanding requests: cost of this issue: | 
| 3300. | 
| volume i number 5 | 
| stocked: 40 outstanding requests: cost of this issue: | 
$3.00. | 
| volume 1 number 6 . | 
| stocked: 35 outstanding requests: cost of this issue: | 
| See e | 
| volume 2 number 1 | 
| stocked: 30 outstanding requests: cost of this issue: | 
| S300. | 
| | 
| number of issues stocked: 205 | 
| number of requests pending: ) | 
| total stock value: $661.00. 
| £,09:13 0.443 96 | 
| | 
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ADDITIONAL BREAK CONTROL 


® ONE MORE BREAK CONTROL REQUEST 


I THE continue _to REQUEST 


I CAUSES probe TO CONTINUE EXECUTING, BUT ONLY UNTIL LINE 


I 


SPECIFIED 


USAGE: 
continue to <line> 


et <line> 


EXAMPLES: 
continue _to 75 


ct +l 


NOTES: 


THE FPIRST EXAMDLE RESUMES EXECUTION OF THE PROGRAM AND STOPS 
IN probe AT LINe 75 OF THE PROGRAM 


THE SECOND EXAMPLE RESUMES EXECUTION, BUT STOPS BEFORE THE 
NEXT STATEMENT (I.E. EXECUTE ONE STATEMENT); SEE THE step 
REQUEST LATER 
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| | 


probe check back issues 
Using check back issues (no active frame). 
position position file 
position file: 
proc (first vol, first num); 
a 
Break set after line 129 
status 
Break exists after line 129 in check_back_issues 
g 
£09220 Ocs2) 220 


check _back_ issues 
From (specify vol:num): 2:1 


to (specify vol:num):3:1 

Stopped after line 129 of position file. (level 32) 
v first vol 

first vol = 2 

vy first num “ 
first num = 1 
“ps +3 ° . : 


om cee OT ene meee SHO nine | nN eee ecg enn NS cee NEP ee eiteeD SOND nn te eee 


end; 
a 
Break set after line 146 
continue to 132 | 
probe (continue to): Using line 144 of check back issues instead.| 
Stopped before Tine 144 of position file. (level 8) | 
sc | 

do while (first vol > current volume); | 
v first vol = a | 
first vol = 2 | 
vy current_volume | 
Current volume = 4.30337e9 
sb current volume 

fixed bin (17) automatic 

Declared in check _back_issues 
q 
ro 09:25--0.831 265 


pwns ene ce er ee ee mmimreny SED mm men EEA teen meena enim meen mere wetectey emma mene eee Aen SO ee en cee see 
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gedx 

rcheck back issues.pll 

/dacl (Current _volume/ 

dcl (current_volume, current _number) fixed bin; 

s/;/ init (0);/p 

del (current_volume, current_number) fixed bin init (0); 
W 


g 

rc 09:27 0.283 33 

pll check _back_ issues -sv2 -tb 
PL/I 26a 

© 09827 34520) 2:30 


close file back issues 
r 09:28 0.044 48 


re ree ae emmaiinenamelitnmmmdiemmnnd 
a a ne ee ee eet 
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(ga ne My a a en ee ee me ee ee eee 
check back issues 
from (specify vol:num):2:1 


| 

| 

| 

| 

| to (specify vol:num):3:1 

| 

| volume 2 number Z 

. , stocked: 36 outstanding requests: 1 cost of this issue: 
300% 

| volume 2 number 3 

| stocked: 46 outstanding requests: 7 cost of this issue: 

| 53000). 

| volume 2 number 4 

| stocked: 31 outstanding requests: Q cost of this issue: 

| $3.00. 

| volume 2 number 5 

stocked: 36 outstanding requests: 0 cost of this issue: 

| 33500 % 

| volume 2 number 6 

stocked: 33 outstanding requests: 

| $13..00% 

{| volume 3 number 1 

stocked: 47 outstanding requests: 5 cost of this issue: 

| S34 00% 

| volume 3 number 2 

| stocked: 50 outstanding requests: 4 cost of this issue: 

| $.3..00: . 

| 

| 

| 

| 

| 

| 


t~ 


cost of this issue: 


number of issues stocked: 279 
mumber of requests pending: 18 
total stock value: So3 7.00% 

r 09:28 0.395 30 


ett SE ete cues ON TO md cptnies RE cats A el ge eet nts te ee Om ne SOD cant cp tN eee 


& TWO MORE BREAK REQUESTS 


I THE reset REQUEST 


I DELETES SPECIFIED BREAKPOINTS 


(RESET BEING A HARDWARE TERM FOR TURNING A SWITCH OFF) 
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ADDITIONAL BREAK CONTROL 


reset <location> 

gr <location> 

reset <program name> 
r <program name> 
reset -all 

r -all 

reset * 


r * 


EXAMPLES: 

reset after 75 
reset 

reset other-prog 


r * 


NOTES: 


THE "reset *" and “reset ~-all" 


ARE IDENTICAL: THEY BOTH 


DELETE ALL BREAKPOINTS IN ALL PROGRAMS 


I THE step REQUEST 


EXECUTES ALL THE INSTRUCTIONS UP TO, 


NEXT STATEMENT 


USAGE: 


step 


Not To Be Reproduced 


BUT NOT INCLUDING, THE 


Fai 


ADDITIONAL BREAK CONTROL 


J EXAMPLES: 
step 


Ss 


I NOTES: 


ACTS JUST LIKE EITHER OF THE FOLLOWING: 


continue to +i 
before +l:(reset; halt) 


IS DEFINITELY MORE CONVENIENT 


Not To Be Reproduced 2-48 


ADDITIONAL BREAK CONTROL 


SEP Oe gh Gee epg = ee ae ee Te Gag OT Oey LON ee OS See ee Gee ee en ee ey 


pb check back issues 
Using check back issues (no active frame). 
ps position file 
position file: 
proc (first_vol, first_num); 
a 
Break set after line 129 


q 
r 09:30 0.247 98 


check back issues 
from (specify vol:num): 2:1 


to (specify vol:num):3:1 
Stopped after line 129 of position_file. (level 8) 


sk 8,2 
8 position_file (line 129) 
7 check back issues (line 58) 


sc | 
position file: 
proc (first vol, first_num); 


step ; 
Stepped before line 144 of position file. (level 8) 


sc 
do while (first vol > current_volume) ; 


ps “return" 
return; 


b 
Break set before line 152 


oe — meee canes 
ceuemeey ese mementos cermin cree Se SS A ee SO ers ct ee oe ee eee ey — 
sce tcc cee nteinte cat come iY SE SEE Weems reins Stew SN cme NY SIERO SEES evens came emus SON eee remo SE cay OE NS ED EE ce cme eee, 
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status 
Break exists before line 152 in check back issues 
Break exists before line 144 in check _back_ issues | 
Break exists after line 129 in check back issues | 


reset 144 
Break reset before line 144 in check _back_issues 
Stopped before line 152 of position_file. (level 8) 


vy current volume 
current volume = 2 


v current number 


| 

| 

| 

| 

| 

| 

| 

| 

| 

| continue 
| 

| 

| 

| 

| 

| current_number = 1 
| 

| 


q 
r 09:39 1.492 420 


Not To Be Reproduced 2-50 Rea 


ADDITIONAL BREAK CONTROL 


I TECHNIQUE 


J] DETERMINE THAT CORRECT NUMBER OF RECORDS ARE BEING PRINTED 
OUT, BUT THAT THE STARTING POINT IS INCORRECT 


] DECIDE THAT THE PROGRAM “position file" IS THE PROCEDURE THAT 
SETS THE STARTING POINT 


REAKPOINTS WITHIN “position file“ TO CHECK THE SETTING 
ES 


B K 
pias | TARTING POINT 


I SEE THAT "position file" POSITIONS TO THE FIRST DESIRED 


RECORD 


I CONCLUDE THAT "print record" DOES NOT HAVE TO READ THE FIRST 
RECORD ~ 
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Dc 


qx 
recheck back _issues.pll 
/call get_record/ 
call get_record (); 
i 


Ne 
/return/ 


if have_used_ record then 


return; 
~l 


| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
have_used_record = "1"b; 

Xe | 
a | 
\é 
/position file/ | 
position file: | 
/return/ | 
return; | 

ay | 
| 

| 

| 

| 

| 

| 


e : 
have used record = "0"b; 


\é 

Bev acton ag 

del back issues file; 
af 
del have_used_record bit (1) aligned; 
NE 


WwW 

g 

r 09:43 0.637 104 

pll check back issues -sv2 -tb 


PL/I 26a 
r 09:43 3.814 183 


i te ce rr rrr meee en TN teen eaten tee ey eevee ence AOR ts em te ee eS SN scent Se Rintam Sewn 


| 
| 
| 
| 
| 
| 
| 
| 
| 
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close file back issues 


r 09:43 0.050 29 


check_back issues 


from (specify vol:num) :2:1 


to (specify vol:num):3:1 


| 

| 

| 

| 

| 

| 

Pacts AAs 

|} volume 2 number 2 

| stocked: 30 outstanding requests: cost of this issue: 
| $3.00. | 
| volume 2 number 2 | 
| stocked: 36 outstanding requests: cost of this issue: | 
| 53.00: | 
| volume 2 number 3 | 
| stocked: 46 outstanding requests: cost of this issue: | 
| $3.00. | 
| volume 2 number 4 | 
| stocked: 31 outstanding requests: cost of this issue: | 
| $3.00. | 
| volume 2 number 5 | 
stocked: 36 outstanding requests: cost of this issue: | 
| $3.00. | 
| volume 2 number 6 | 
| stocked: 33 outstanding requests: cost of this issue: | 
| 53500. | 
| volume 3 number 1 | 
| stocked: 47 outstanding requests: cost of this issue: | 
| $2200, , 
| 

| number of issues stocked: 259 | 
| mumber of requests pending: 16 | 
| total stock value: S77 7200% | 
| r 09:44 0.459 14 | 
| | 
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PROBE ODDS AND ENDS 


= A FEW MORE COMMANDS 


I THE halt REQUEST 


I CAUSES PROBE TO BE ENTERED AT BREAKPOINT EXECUTION TIME 


[ USAGE: 


hale 


ONLY USEFUL IF NOT EXECUTING IN PROBE ALREADY 


A BREAKPOINT SET IN THE FORM OF "after" IS REALLY 
t tee 7 


|. THE pause REQUEST 


I ACTS LIKE THE halt REQUEST, BUT ALSO RESETS THE BREAKPOINT 


. USAGE: 


pause 


p 
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PROBE ODDS AND ENDS 


I. EXAMPLE: 
pause 
P 

{ NOTES: 


LIKE THE halt REQUEST, IS ONLY USEFUL AT A 


the BREAKPOINT “after:pause”™ IS EQUIVALENT 
t;reset) 


I THE list_builtins REQUEST 


I LISTS THE BUILTIN FUNCTIONS AVAILABLE FROM 


. USAGE: 
list builtins 


1b 


. EXAMPLES: 
list builtins 


lb 


I THE list_help REQUEST 


BREAKPOINT 


TO "after: 


WITHIN probe 


IT LISTS ALL THE HELP FILES AVAILABLE THROUGH THE probe “help” 


REQUEST 


I USAGE: list_help 
lh 
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PROBE ODDS AND ENDS 


[ EXAMPLES: 
list help 
lh 
NOTES: 


YOU CAN GET MORE THAN JUST HELP ON THE REQUESTS: 
DESCRIPTIONS ARE ALSO PROVIDED FOR THE ARGUMENTS TO probe 
REQUESTS 


@ SPECIFYING LINES 


I SEVERAL PROBE REQUESTS ACCEPT LINE NUMBERS AS THEIR ARGUMENTS 
I before 
i after 


reset 


+ 


1 status 


] SPECIFICATION OF A LINE CAN TAKE ON MANY FORMS 


I ABSOLUTE LINE NUMBER 


I RELATIVE EXECUTABLE STATEMENT 


+1 
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+50 
=5 


USING LABELS 
get_record 
place (3) 
Senewneee, 2 


$100 


SPECIAL SYMBOLS 


S¢ 
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F2 
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TOPIC; tLt 


Other Source-Level Debugging Commands . 
The trace Command . . . . « «ee « » 
Interaction of the Control Arguments 
Tracing Example One . . . . « «© « « 
Other trace Control Requests. .. 
Trace EXaMole “TWO. .e oe 4 lew. a Ow 
The display pllio error Command . 
A display pllio error Example .. 


e 
e 
* 
® 


e e 6 e eo e e e 


e e © e e 2 ° e 


e * ° ° e ® ° e 


e e e ® . e 


Topic III SOURCE-LEVEL DEBUGGING (TRACE) Topic IIL 
OBJECTIVES: 


Upon completion of this toric, students should be able to: 


1. Add and remove procedures to and from the trace table. 


nj 
om 


dify the tracins of a particular procedure in the trace 
Kies 


o 
a 


3. Use the trace command to Perform meterins on selected 
Procedures. 


4. Monitor recursion of selected procedures. 


Multics IIli-14 F214 


B 


THE TRACE COMMAND 


trace COMMAND 


IT SOURCE-LEVEL, PROCEDURE-CALL MONITOR 


I CAN BE USED WITH PROGRAMS WHICH DO NOT HAVE SYMBOL TABLES 


I CAPABILITIES INCLUDE 


I PRINTING ARGUMENTS AT PROCEDURE ENTRY AND/OR EXIT 


IT EXECUTING A MULTICS COMMAND LINE AT PROCEDURE ENTRY AND/OR 


EXIT 


I STOPPING (BY CALLING THE COMMAND PROCESSOR) AT PROCEDURE 


ENTRY AND/OR EXIT 


I CONTROLLING THE FREQUENCY AT WHICH TRACING MESSAGES ARE 


PRINTED 


I WATCHING UP TO 16 STORAGE LOCATIONS FOR CHANGES .AT SVERY 


PROCEDURE ENTRY AND/OR EXIT 


J LIMITATIONS 


I ONLY EXTERNAL PROCEDURES COMPILED BY PL/I OR FORTRAN CAN BE 


TRACED 


IT ONLY USER-RING PROCEDURES CAN BE TRACED, NOT SUPERVISOR OR 


GATE PROCEDURES 
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THE TRACE COMMAND 


A BOUND SEGMENT CAN BE TRACED ONLY IF ITS. 
mama?z froma rarenh FAT eS MArray fone aad Fh Gino) 
Ge 


RGaLALNGL IN THE BOUND SEGMENT 


trace -control_ args 
OR 
trace procedure names 
OR 
trace -control args procedure names 
al procedure names GIVE THE PATHNAME OR REFERENCE NAME OF A 
PROCEDURE ENTRY POINT TO BE TRACED 
jirectory path>entryname 
directory path>entrynameSentry point _name 
reference name 


reference nameSentry point _name 


I control_args CONTROL THE TRACING FUNCTIONS PERFORMED ON THE 
TRACED PROCEDURE 


I OPERATION 


T trace COUNTS 


I] HOW MANY TIMES A PROCEDURE IS CALLED (N = NUMBER OF CALLS) 
IN THIS PROCESS SINCE COUNTERS WERE LAST RESET 


JT HOW MANY TIMES A PROCEDURE IS MONITORED WHILE A PREVIOUS 
ACTIVATION STILL EXISTS (R = RECURSION DEPTH) 
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THE TRACE COMMAND 


IT OPERATION (Continued) 


[ trace MONITORS A PROCEDURE CALL 
J WHEN N AND R MEET CERTAIN CRITERIA 


I BY PRINTING MONITORING MESSAGES 


Call N.R of PROCEDURE from CALLING PROC, ap=244|1746. 


Return N.R from PROCEDURE. 


IT BY OPTIONALLY PRINTING PROCEDURE ARGUMENTS BEFORE ENTRY OR 


AFTER EXIT 


IT BY OPTIONALLY GOING TO Multics COMMAND LEVEL 


OR INVOKING A 


USER-SPECIFIED PROCEDURE BEFORE ENTRY OR AFTER EXIT 


4 


MONITORING CRITERIA 


IT ARE STORED IN A TRACE CONTROL TEMPLATE (TCT), 


STATIC DATABASE IN THE PROCESS DIRECTORY 


I FOR &ACH TRACED PROCEDURE ARE STORED 
FASHIONED AFTER THE TCT 


te 


IN THE TCT ARE PRINTED BY 

trace -template 
tT ARE SET BY GIVING A trace COMMAND WITH 
control args: 


-~first F, -ft F 
MONITOR WHEN F<=N 


-last L, -1lt L 
MONITOR WHILE N<=L 


~-every E, -ev E 
MONITOR EVERY Eth CALL (WHEN mod(N,E)=0) 


-before B 


STOP BEFORE ENTERING PROCEDURE IF B”=0 AND Pog B) =0 


AND mod(N,£)=0 


-after A 


STOP AFTER ee PROCEDURE IF A°=0 AND mod{N,A)=0 


AND mod(N,&)= 
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P2i 


THE TRACE COMMAND 


-argument AG, -ag AG 
pnrarTtrxrm A TOS TIAA THAT 
TALIS IM iN 


mod (N,E)=0 


ma ro an 
Wart ty 4wuo 4, £ 


-in PRINT ARGUMENTS ONLY BEFORE ENTRY 
~out PRINT ARGUMENTS ONLY AFTER EXIT 


-inout 
PRINT ARGUMENTS BEFORE ENTRY AND AFTER EXIT 


“depth D, ~dh D 
MONITOR ONLY IF R<=D AND GOVERNING IS OFF 


-return value jonloff}, -rv fonljoff} 
PRINT FUNCTION RETURN VALUE AFTER EXIT 


-govern {fonloff}, -gv fonloff} 
DISABLE RECURSION DEPTH CHECKING; INSTEAD, PRINT THE 
CALL MESSAGE ONLY WHEN THE RECURSION DEPTH REACHES A 
NEW MAXIMUM. ALSO, STOP WHEN RECURSICN DEPTH IS A 
MULTIPLE OF 10 & A NEW MAXIMUM. 


-meter fon|loff}, -mt {on|off} 


DISABLE MONITORING AND ENABLE PERFORMANCE METERING OF 
THE TRACED PROCEDURES 
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INTERACTION OF THE CONTROL ARGUMENTS 


trace -first 5 -last 12 -every 2 -before3 -argument 4 


COISSSSS 


“er OOOO 


MONITOR EVERY 
2nd CALL 
(-avery 2) 


STOP BEFORE 
EVERY 3rd CALL 

(iF iT’S MONITORED) 
{(-befora 3) 


PRINT INPUT ; 
ARGUMENTS EVERY 
4th CALL (IF IT’S 
MONITORED) 
(-argument 4) 


Fei 


TRACING EXAMPLE ONE 


Bg a pg a ae ee ay a ee ee ae 


return (fr); 
end fact _; 


| 1 fact_: procedure (n) returns (fixed dec (12)); | 
| 2 del (n, £, rv) £ixed dec (12); | 
bh 3 if n <= 1 then r = 1; | 
| 4 else do; | 
| 5 f = fact_ (n-1); | 
| 6 r=f£f* n; | 
ae end; | 
| 8 | 
| 9 | 
| 


— 


| 1 factorial: procedure; | 
| 2 del result fixed dec (12); | 
| 3 dcl fact _ entry (fixed dec (12)) returns (fixed dec (12)); | 
| 4 del n fixed dec (12); | 
| 5 dcl cleanup condition; | 
| 6 dcl (sysin, sysprint) file; | 
| 7 epen file(sysin) stream input, | 
| 8 file(sysprint}) stream output | 
| 9 env (interactive) ; | 
{ 10 on cleanup close file (sysin), file (sysprint); | 
I” <2 get file (sysin) list (n); | 
ke fee do while (n >= 0); | 
| 13 result = fact (fn); | 
| 14 put file (sysprint) list (result); | 
as get file (sysin) list (n); | 
| 16 end; ‘ | 
ee close file (sysin), file (sysprint); 4 | 
| 18 end factorial; | 
| | 


ny 
h 
t— 
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TRACING EXAMPLE ONE 


—— 


Gre rg rs ae ee ee 


| 1 l pli face. 
| 2 PL/I | 
| 3 r i720 1.3383 23.776 148 | 
| 4 | 
| 5 ! pll factorial | 
6 PL/I 
7 r 1720 0.964 1.332 36 : 
| 8 

| 9 ! factorial 
| 10 Lg 
| Vi 6 
| LZ 1 4 | 
| i 24 | 
| 14 t «<5 
15 120 | 
| 16 i 5 | 
| L7 720 | 
| 18 29 
19 3628800 | 
| 20 $ <1] 
21 te Li2l 83303 0.342 25 | 
| 22 : 
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TRACING EXAMPLE ONE 


lp Re ee ee 


| 23 1 trace -template . | 
24 first: 1, last: 9999999999, every: l, | 
25 before: 0, after: 0, args: 0, depth: 9999999999, 
| 26 meter: off, govern: off, return_value off | 
| 27 yr 1721 0.067 0.042 6 | 
| 28 | 
29 ! trace -arguments 1 -out -return_value on | 
| 30 vr L172) 6 s038' 0.002 1 | 
| 31 | 
| 32 1 trace fact_ | 
| 33 yr A721 0.155°0.506 22 | 
34 ? | 
| 35 1 factorial 
| 36 ES NR | 
| a7 “Call 1.1 of fact_ from factorial|235, ap = 24415254 | 
| 38 Call 2.2 of fact_ from fact_|43, ap = 24415600 | 
| 39 Call 3.3 of fact. from fact |43,; ap = 244/6120 | 
| 40 Call 4.4 of fact _ from fact_|43, ap = 24416440 | 
| Al Call 5.5 of fact _ from fact_|143, ap = 244]6760 | 
| 42 Return 5.5 from fact_ | 
| 43 ARG 1 @ 24416750 = 1 | 
| 44 ARG 2 @ 24416740 = 1 | 
| = 45 Return 4.4 from fact_ | 
| 46 ARG 1 @ 244|6430 = 2 | 
| 47 ARG 2 @ 244|]6420 = 2 | 
48 Return 3.3.from. fact. . 
| 49 ARG 1 @ 2441/6110 = 3 | 
| 50 ARG 2 @ 244{6100 = 6 | 
| 51 Return 2.2 from fact_ | 
| 52 . ARG 1 @ 24415570 = 4 | 
| 53 ARG 2 @ 244|5560 = 24 | 
| 54 Return 1.1 from fact_ | 
| 55 ARG 1 @ 2441/5144 = 5 | 
| 56 ARG 2 @ 244|5140 = 120 | 
| 5.7 120 | 
| 58 }  -1 | 
| 59 roi/721. 0.395 1.632 47 
| 60 | 
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TRACING EXAMPLE ONE 


~~) 
on 


trace -every 3 


| | 
| 62 yr 1722-.0.021 0,000 0 | 
| 63 | 
| 64 ! trace Fact_ | 
| 65 r 1722 0.024 0.000 0 | 
| 66 | 
| 67 { factorial 
| 68 ! 10 | 
| 69 Call 6.1 of fact _ from factorial|235, ap = 24415254 | 
| 70 Call 9.2 of fact _ from fact_|43, ap = 2441/6100 | 
oe Call 12.3 of fact_ from fact_|143, ap = 24416720 | 
| 72 Call 15.4 of fact_ from fact_|43, ap = 24417540 | 
| 73 Return 15.4 from fact_ | 
| 74 ARG i @ 24417530 = 1 | 
| 75 ARG 2 @ 244/7520 = 1 | 
| 76 Return 12.3 from fact_ | 
| Vd ARG 1 @ 24416710 = 4 | 
| 78 ARG 2 @ 2441/6700 = 24 
78 Return 9.2 from fact_ | 
| 80 ARG 1 @ 24416070 = 7 | 
| 81 ARG 2 @ 244/6060 = 5040 | 
[| 82 Return) .G.1 from face . | 
| 83 ARG 1 @ 244/5144 = 10 | 
| 84 ARG 2 @ 244/5140 = 3628800 | 
| 85 3628800 | 
i = 86 f 1 | 
| 87 eee Meee OLOO2: & 
| 88 | 
ae at 
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TRACING EXAMPLE ONE 


(a 


| 89 i trace -status fact 
[| 90 fact: ~ | 
91 N= 15 | 
| 92 R = 0, max R = 0 | 
| 33 Fel 
| 94 L = 9999999999 | 
| 95 E = 3 | 
| 96 B= 0 | 
| 97 A = 0 | 
| 98 AG = 1(0) | 
| Be D = 9999999999 | 
| 100 return_value | 
} Lol 
| 102 yr ilv22 0.052 0.000 0 | 
[c 3203 | 
| 104 | trace -status * | 
| 105 15.0 £act_ | 
| 106 yr 1723 0.027 0.000 0 | 
lr 807 | 
| 108 ! trace -reset fact_ -status fact_ | 
| 109 © bact..: | 
| 110 N= 0 | 
b aad R= 0, max R= 0 | 
E Ate F=1 | 
b 23 L = 9999999999 | 
| 114 E= 3. | 
| tS B= 0 
| 116 A = 0 | 
ae oe AG = 1(o) | 
b. “213 D>. 9999999999 | 
| 119 return_value | 
| 120 | 
| 12. cr 1723 0.055 0.006 2 | 
[22 | 
ft 223 ! factorial | 
| 124 1 4 | 
tr 225 Call 3.1 of fact_ from fact_|43, ap = 24415560 | 
| 126 Return 3.1 from fact_ | 
> be? ARG 1 @ 244/5550 = 2 | 
| 228 ARG 2 @ 24415540 = 2 | 
[ 29 24 | 
| 130 1-1 | 
i eee er i724--0.203) 0.000:.0 | 
i 132 | 
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OTHER TRACE CONTROL REQUESTS 


[ OTHER trace CONTROL ARGUMENTS 
J CONTROL THE GENERAL OPERATION OF trace 


I INCLUDE 


-status procedure name, -st procedure name 
PRINTS THE TRACE CONTROL PARAMETERS AND COUNTERS FOR THE 
NAMED PROCEDURE 


~status *, -st * 
LISTS THE PROCEDURES BEING TRACED, THEIR INVOCATION 
COUNTS AND RECURSION DEPTHS 


~reset procedure name, -rs procedure name 
ZEROES THE INVOCATION COUNT OF THE GIVEN PROCEDURE 


-off procedure name 
STOPS MONITORING THE GIVEN PROCEDURE; PROCEDURE REMAINS 
IN TRACE TABLE AND COUNTING OF INVOCATIONS CONTINUES, 
HOWEVER 


-on procedure name 
RESUMES MONITORING THE GIVEN PROCEDURE 


-~remove procedure name, -rm procedure na 


me 
MHA TRI MIT wp wemH! mn sere RE nr 
STOPS TRACING THE GIVEN PROCEDURE, DE 


FOR THE PROCEDURE 
I THE procedure name CReneN ey): FOLLOWING CONTROL ARGUMENTS MUST 
HAVE THE FORM: 
entryname 
entrynameSentry point name 
reference name 


reference nameSentry point name 


* 


THE CONTROL ARGUMENT APPLIES TO ALL TRACED PROCEDURES WHEN * 
IS GIVEN 
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OTHER TRACE CONTROL REQUESTS 


| 
l. 33 1 trace -off fact_ | 
| 134 r 1724 0.022 0.000 0 | 
| 135 . | 
| 136 i. -Eactor iar | 
ae ee ! 12 | 
| 138 479001600 
| 139 , =] | 
| 140 r.1725 0.072 0,000 0 | 
| 141 | 
| 142 1 trace -on fact_ | 
} 143 Ee L723: 0.025 0.000: 0 | 
| 144 | 
} 145 1 factorial 
| 146 tL. 32 | 
| 147 Call 18.1 of fact_ from fact_143, ap = 2441/5420 | 
| 148 Return 18.1 from fact_ | 
} 149 ARG 1 @ 24415410 = 1 | 
150 ARG 2 4 244|5400 = 1 | 
| 151 2 | 
| “£52 { =] | 
; 53 roi7 26: 01.9055" 6..000-:0 | 
| 154 | | 
i Ss ! trace -status * | 
I’. “156 18.0 fact. | 
| 1o.d r 1726 0.028 0.000 0 | 
| 158 3 | 
i; i159 i trace -remove fact 
| 160 r 1726 0.927 9.002 1 
{ 161 | 
| 162 ! trace -status * | 
| 163 trace: Trace table is empty. | 
| 164 r 1727 0.036 0.000 0 | 
| 165 | 
| 166 ! factorial 
| 167 ! 10 | 
168 3628800 | 
| 169 { =] | 
| 170 © 2727. 0.070 0.000 "9 | 
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OTHER TRACE CONTROL REQUESTS 
[ OTHER trace CONTROL ARGUMENTS 


I CONTROL THE GENERAL OPERATION OF trace 


~brief, -b£ 
SHORTENS THE MONITOR MESSAGES 


-long, -lg 
PRINTS LONGER MONITOR MESSAGES AGAIN 


-io_ switch switch name, -is switch name 
PRINTS MONITOR MESSAGES ON THE NAMED I/O SWITCH, WHICH 
MUST BE ATTACHED & OPENED FOR STREAM OUTPUT 


~execute command line, -ex command_line 
EXECUTES THE COMMAND LINE WHENEVER A PROCEDURE IS 
MONITORED 


~stop proc procedure name, -sp procedure name 
CHANGES THE PROCEDURE CALLED TO STOP BEFORE ENTRY OR 
AFTER EXIT TO THE GIVEN PROCEDURE 


T CONTROL PERFORMANCE MONITORING 


-meter fon|loff}, -mt fonloff£} 
STARTS/STCPS METERING OF TRACED PROCEDURES 


-total, <tt 
PRINTS PERFORMANCE MEASUREMENTS AND CLEARS THE METERING 
STATISTICS 


-subtotal, -stt 
PRINTS PERFORMANCE MEASUREMENTS BUT DOES NOT CLEAR THE 
METERING STATISTICS 


Niv C OK te 
I WATCH STORAGE LOCATIONS FOR CHANGES AS PROCEDURES ARE TRACED 
AND STOP IF THE LOCATIONS CHANGE 


~watch location, -wt location 
WATCHES THE ONE WORD LOCATION. UP TO 16 LOCATIONS CAN 
BE WATCHED AT ANY TIME. location HAS THE FORM: 
segment number|loffset 


-watch off, -wt off 
TURNS OFF THE WATCH FACILITY 
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TRACE EXAMPLE TWO 


el..print tt.plll. 


Cus “oroc: 

dcl ioa_ entry options (variable); 

dcl d$ external static; 

dcl mod builtin; 

acl cleanup condit 

on cleanup begin 
counter = 0 
call ‘ioa. ( 

goto bottom; 
end; 


Lon; 


. 
s 
e 
e 
e 


dcl counter fixed bin internal static init 


counter = counter +1; 


Gall ioa ("..° 17, counter); 


if mod (Counter, 5) = 0 then d$ = counter; 


call tt; 
bottom: 
end tt; 


! trace -ft 5 -last 12 -every 2 -before 3 -argument 4 tt 


! trace -status tt 


cos 

N = 0 

R= 0, max R = Q 
Fe=5 

Go = 12 

B= 2 

B= 3 

A = 0 
AG = 4 

D = 99399999999 


! trace -template 


first: 5, last: 12, every: 2, before: 3, after: 
depth: 9999999999, meter: off, govern: off, 


L Tee 

et 

<2 

wd 

234 

ae, 

Call 6.1 of tt from ttl113, ap = 244|[5476 
trace: stop before 

! Amu 


Multics MR6.5+, load 32.0/150.0; 40 users 
Absentee users 0/4 


Call 8.2 of tt from ttj113, ap = 244|6156 
No arguments. 

Rare = 

9 

Call 10.3 of tt from ttl|113, ap = 244/6636 
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counter initialized back to zero."); 


return vVelue GLE 


PZ. 


eae 
ce ae 
Lis 
114 


Not 


TRACE EXAMPLE TWO 


Call 12.468 tt trom ttlili4, ap-= 24417316 
No arguments. 
trace: stop before 


! sr 
ecwace 
eas 
2 ol4 
wee 
sabe 
ake 
s*LS 
2 weedkss 
«a2 
OWLT 
! trace -status tt 
cis 
N = 282 
R= 4, max R = 0 
Fe=5 
L= 12 
E = 2 
B= 3 
A = 90 
AG = 4 
D = 9999999999 


! release -ail 

counter initialized back to zero, 
Return 12.4 from cit 

Recurn 1043 Erom fe 

Return 8.2 from tt 

Return 6.1 Erom tt 

! trace -status tt 

cue 

282 

QO, max R= 0 
5 

GZ 

2 

3 

0 

4 

9999999999 


A 
VUOPraomryaw za 


— cracereyv 


b tracerev trace -ft 1 -lt 93999999999 -ev 1 -before 0 
-after 0 -ag 0 -dh 9999999999 -mt off -gv off -wt off 


~return value off 

! tracerev tt 

! trace -st tt 

Ces 

282 

O, max R = 0 
: 


Cy Oe 


g299999S99 
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TRACE EXAMPLE TWO 


niu nw ut 
WOoooOr 


999999999 
1 list ref names d 
357 


trace -watch 35710 

trace tt 

ja 

wad 

wie 

aes 

aed 

“Ko 

trace print_: 35710 = 000000000005 
Call 288.6 of tt from ttl113, ap = 2441/6556 
trace: stop before 

i Start 

250 

eid 

<8 

a9 

a0 

trace print_: 35710 = 000000000012 
Call 293.11 of tt from tt|]113, ap = 244/10576 
trace: stop before 

1 start 

ge bd 

eee ee) 

eas 

- 14 

fis 

trace print : 3571/0 = 000000000017 
Call 298.16 of tt from ttl113, ap = 244112616 
trace: stop before 

! rl -all 

counter initialized back to zero. 
! tracereyv tt 

! trace ~-st tt 

i 


om ame ame (), 


298 

0, max R = 0 
1 

9999999999 

1 

0 

0 

0 

9999999999 


» 
ONO PrUwmraAD a! 


ubhunk td Goo ao tt 


! trace -reset tt 
! trace -govern on tt 
Poe 
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TRACE EXAMPLE TWO 


Call 1.1 of tt from command processor 13304 (read list), 
ap = 244|4600 
ae : 
Call 2.2 of tt from ttl113, ap = 244/5056 
bee 
Call -3.3°0f-C&- Erom ttliis, ep = 24415376 
ees 
Call 4.4 of tt from ttj113, ap = 24415716 
204 
Call 5.5 of tt from tt/113, ap = 24416236 
tao 
trace print_: 357/0 = 000000000005 
Cail 6.6 of et from tt!113, ap = 244/6556 
sas 
Call 7.7 of tt from tt|l113, ap = 244|7076 
saat 
Call 8.8 of tt from tt]113, ap = 244|7416 
“eo 
Call 9.9 of tt from ttl/113, ap = 244|7736 
eo 
Call 10.10 of tt from tt/113, ap = 244(10256 
trace: stop before 
! trace -prief tt 
L-Stare 
eee 
trace print: 35710 = 000000000012 
Cali Lied: Ones 
ase 
Cab T2002 Of. Er 
Pere ee 
Catt 15.18. on Se 
4 ee : 
Call 14.14 of tt 
»L4 
Cai 2561505 ee 
trace print _: 3571/0 = 000000000017 
Call: 16.06 Of; 25 
k6 
Call 27 617 “of OEE 
ab 
Cali 13418: Of Et 
cine 
Call 19.19 of tt 
SeL9 
Cail 20.20 of Sf 
trace: stop before 
OULT 
! trace -watch off tt 
{ sr 
! ready 
r 1842 9.009 21.098 724 level 2, 51 
L- Sf 
“= 20 
Cari 21aZl et. te 
pe 
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TRACE EXAMPLE TWO 
228. Call 22.22-0f -t& “sete ? 


229° #22 
230° Call 23.23 o£ et 
Za. s523 


232 Call 24.24 of tt 


234. Cali 25.25. -0f tt 


235 «425 
236 Call 26.26 of tt 
237 ..26 
238 Call 27.27 of tt 
239° “427 
240 Call 28.28 of tt 
241 ..28 
242 Call 29.29 of tt 
243 ..29 


244 Call 30.30 of tt 
245 trace: stop before 


246 QUIT 

247 ! rl -all 
248 counter initialized back to zero. 
249 ! trace -st tt 

250 itt: 

251 N = 30 

252 R = 0, max R = 30 
253 F = 1 

254 L = 9999999999 
255 E=l 

255 . B= Q 

io ej A = 0 

258 AG = 0 

259 D = 9999999999 
260 govern 

261 

262 ! trace -govern off tt 

263 ! trace -st tt 

264 tt: 

265 N = 30 

266 R= 0, max R = 30 
267 F=tl 

268 L = 9999999999 
269 E=l1 

270 B = 0 

271 A = 0 

272 AG = 0 

273 D = 9999999999 
274 

275 ! trace -reset tt 

276 ! ‘trace ~st tt 

Z2i7y “tes 

278 N = 0 

279 R = 0, max R = 30 
280 F = ] 

281 L = 9999999999 
282 E= 1 

283 B= 0 

284 A = 0 
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F2 


285 _ AG 
286 D 


0 


Not To Be Reproduced 


TRACE EXAMPLE TWO 


9999999999 


Pee 


THE DISPLAY PL1IIO ERROR COMMAND 


JI PRINTS ADDITIONAL INFORMATION ABOUT THE MOST RECENT 
CONDITION SIGNALLED BY THE PL/1 INPUT/OUTPUT FACILITY 


T USAGE 
display pllio_error 
OR 


dpe 


I PL/1 I/0 ERROR CONDITIONS INCLUDE 


I endfile 
IT key 
IT name 


IT recor? 


[ transmit 


. undefinedfile 
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ERROR 


E2i 


A DISPLAY PLIIO ERROR EXAMPLE 


| 1 write file: procedure; | 
2 | 
| 3 dcl f£ file record output; | 
4 dcl. tecl char (10), 
| 5 rec2 char (30) varying; | 
6 del cleanup condition; 
| 7 | 
| 8 
9 on cleanup close file (£); | 
220 open file (£); | 
> “er 
i. olee recl = "ABCDEfghij"; | 
b 23 write file (£) from (recl); | 
| 14 | 
E ak rec2 = “abcdeFGHIJ"; 
| 16 write file (£) from (rec2); | 
a | 
| 18 close file (£); | 
| 19 | 
| 20 end write file; 
| | 


1 

2 

3 dol. £ ‘file record inpee: 

4 dcl sysprint file; 

5 deci yrecl ‘char (10); 

6 acl (cleanup, endfile) condition; 
5 

8 
9 


on cleanup close file (£), file (Sysprint); 
oper file -(£)-; 


LO file (sysprint) output stream env (interactive) ; 
sas 

iS do while (“1i"b); 

14 read file (£) into (recl); 

£5 put file (Sysprint) list (recl); 
16 end; 

Li 

18 DONE: 

19 close file (f£), file (sysprint); 

20 

2d end read file; 


| | 
| | 
| | 
| 
{| | 
| 
| 
| | 
| 
| | 
I. 12 on endfile (£) go to DONE; | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
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A DISPLAY PLIIO ERROR EXAMPLE . 


A ES CERN ED 


— # 


| 
| 1 ! pill read_file -table 
| 2 PL/I | 
| 3 Ci A034 Las53. Siw Slo 272 | 
| 4 | 
| 5 ! pli write file -table | 
| 6 PL/I | 
q r 1034 0.767 40.527 287 | 
8 | 
| 9 ! read file | 
| 10 is | 
pil Error: undefinedfile condition 
| 12 by >udd>F19d>Friedman>read filel177 (line 9) | 
| 13 occurred while doing I/0 on file f | 
| 14 File cannot be opened: call to iox Sopen fails. | 
| 2 system handler for error returns to command level | 
| 1 r 1034 0.169 5.250 74 level 2, 16 | 
| 17 | 
| 18 ! display pllio_error | 
| 19 | 
| 20 Error on file £, status code: Entry not found. 
“ed Title: vfile ¢£ | 
| 22 Attributes: input notkeyed record sequential | 
| 23 Permanent attributes: input record | 
| 24 Error in opening or closing f | 
| 25 r 1035 0.069 1.470 37 level 2, 16 | 
| 26 | 
| 27 ! probe | 
| 28 Condition undefinedfile raised at line 9 of read_file. 
| 29 ! source | 
| 30 open file (f), | 
| 31 file (sysprint) output stream env (interactive); | 
| 32 ! quit | 
33 r.2035-0.120: 5,726 9% Level 2 16 | 
| 34 | 
| 35 ! release | 
36 Gr 1035 0.5028 0.325) 17 | 
| 37 : | 
| | 
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A DISPLAY PLIIO ERROR EXAMPLE 


Sc Ce 


38! write file 


| | 
| 39 | 
| 40 Error: undefinedfile condition | 
| 41 by >udd>Frl9d>Friedman>write file|133 (line 10) | 
42 occurred while doing I/O on file £ | 
| 43 File cannot be opened: | 
| 44 . ainput and output attributes conflict. | 
| 45 system handler for error returns to command level | 
| 46 r 1035 0.140 3.660 60 level 2, 16 | 
| 47 | 
| 48 ! dpe | 
| 49 | 
| 50 Error on file £ | 
| oes Title: ville. £ | 
| 52 Attributes: input output record 
| 53 Permanent attributes: input output record | 
| 54 Error in opening or closing f | 
| 55 The output attribute conflicts with the input attribute. | 
| 56 r 1036 0.061 1.190 34 level 2, 16 | 
| 57 | 
| 58 ! new_proc | 
| 59 fr 1037 0+184 8372 91 | 
| 60 7 | 
| 61 ! write file | 
| 62 yr o1037 0.376 6.532 80 | 
63 
| 64 ! read_file 
| 65 | 
| 66 Error: undefinedfile condition | 
| 67 by >udd>F19d>Friedman>read_file|177 (line 9) 
| 68 occurred while doing I/0 on file £ | 
| 69 File cannot be opened: | 
| 79 input and output attributes conflict. | 
Ti system handler for error returns to command level | 
! Le r 1038 0.627 25.122 192 level 2, 16 | 

73 | 
74 1! new_proc | 
75 r 1039 0.236 4.830 69 | 
76 | 
| | 
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A DISPLAY PLIIO ERROR EXAMPLE — 


ener smears wm EE eee eee EHS Gree Gente gpm GOTee ST Seem GERI Se Ge RT SR EN UU TEE IER peeeee GUE ere amNY SA Gat GN meen nee cnet wmuanan Sunt 


om 


read file 
ABCDEfghij 


Error: record condition 

by >udd>F19d>Friedman>read_ file|241 (line 14) 
occurred while doing I/O on file £ 
"read into(XX)": 

record in data set larger than variable XxX. 
Type “start" to continue. 
Data will be truncated to record's length. 
system handler for error returns to command level 
r 1039 0.887 25.244 219 level 2, 16 


dpe 


Error on file £, status code: Record is too long. 
Title: vtile. =f 

Attributes: open input notkeyed record sequential 
Permanent attributes: input record 

Last i/o operation attempted: read into 

yr 1040 0.106 3.540 59 level 2, 16 


probe 
Condition record raised at line 14 of read file. 
source 
read file (£) into (recl); 

v recl 

"\000\000\000 
abcderF" 
quit 
r 1041 0.368 11.650 192 level 2, 16 


Start 

\000\000\600 

abcderF 

r 1041 0.119 3.492 59 
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Ped 


A DISPLAY PLIIO ERROR EXAMPLE 


| 114 ! print_attach_table £ 

Eb as £ (not attached) 
| 116 r 1041 0.069 1.640 40 

| i117 

| 118 ! io call attach f vfile_ f 

} 119 r 1041 0.080 3.306 57 

| 120 

| 121 ! io open £ sequential input 

| 122 r 1042 0.087 3.422 58 

I 123 

| 124 ! io read_length f 

} 125 io call: len=10. 

| 126 r 1042 0.039 0.006 2 

ib! lay 

| 128 ! io read £ 10 

| 129 io_call: 10 characters returned. ABCDEfghij 
| 130 r 1042 0.077 1.980 44 

bP 32 

| 132 ! io read_length £ 

LY 233 io call: len=34. 

| 134 r 1042 0.032 1.332 36 

b- 38 

| 136 :! tio read £ 40 

oe io call: 34 characters returned. \000\000\000 
| 138 abcdeFGHIJ\400#\400\000\000\000write file 
} 139 r 1042 0.050 1.980 44 

| 1406 

| 141 ! to (elose detach) €£ 

| 142 r 1043 0.045 2.162 46 

| 
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TOPIC LV 


Advanced probe Requests . ..c« © Ns 
INETOGUCT LON 6 ee Go oe Sac Se Ser Ae ec 
Scenario I - More probe Control . 
Control of Output Processing. .. 
Scenario III = Program Manipualtio 


° 


nh 


e o eo e e 


a 9° e C) ® 


e 6 9 8 ® 


4-1 
4=—1 
4=2 
4=7 
4~9 


Toric IV. 


OBJECTIVES: 


Upon completion of this topic, 


1. Use the followins eprsbe reausests to good advantase: 


Multics 


ADVANCED PROBE REQUESTS. 


wedee 

if 

language (lng) 
display (ds) 
goto (3) 

where (wh? 

use 

call (el) 
deciare (decl> 


listuvariablas (Isv)} 


IV-1 


. Terie LV 


students should be able to: 


F211 


INTRODUCTION 


® MORE ABOUT probe 


. MOST DEBUGGING CAN BE DONE USING THE TECHNIQUES DESCRIBED IN 
CHAPTER TWO 


I THE REQUESTS DESCRIBED HERE GIVE THE USER MUCH MORE CONTROL OVER 


muD PROBE ENVIRONM arm 


* bid Pa hae) dat LY de INNES LLY 


I THE CONTROL CAN BE THOUGHT OF AS COVERING DIFFERENT ASPECTS OF 
probe 


[ CONTROL OF THE INTERACTION 


. modes 

i. 2 

I language 
I display 


1 CONTROL OF PROGRAM USAGE 


I goto 
I where 
I use 

T call 


IT CONTROL OF PROBE VARIABLES 
I declare 


I list_variables 
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SCENARIO I = MORE PROBE CONTROL 


® NEW REQUESTS 


I] THE modes REQUEST 
I ALTERS THE WAY probe INTERACTS WITH THE PROGRAMMER 


T USAGE: 
modes 
mode 
modes <mode type> <mode value> 


mode <mode type> <mode value> 


EXAMPLES: 


4 


modes prompt on 


; % 
Modes oromoe string 


Ke it 
a hd o 


n 
Iss 


mode value separator " is equal to " 


[ NOTES: 

SUPPORTED MODES ARE: 
error messages, em 
qualification, gf 
value print, vo 
value separator, VS 
prompt 


prompt string 
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SCENARIO I = MORE PROBE CONTROL 


A A A 8 = <oeceeeeeee 


I THE language REQUEST 


[T ALLOWS THE PROGRAMMER TO LET probe INTERACT IN DIFFERENT 
DIALECTS 


J USAGE: 
language 
ing 
language <lanquage> 


Ing <language> 


[T EXAMPLES: 
language 
Ing 


language fortran 


L “NOTES: 


THE LANGUAGES CURRENTLY SUPPORTED ARE pll, fortran, AND cobol 


I THE goto REQUEST 


I GIVES BETTER ERROR PROCESSING CONTROL 


. USAGE: 
goto <line> 


g <line> 


IT EXAMPLES: 
Soco.50 


g 1-23 
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ry} 
nh 
4 


SCENARIO I - MORE PROBE CONTROL 


qa Se 


“ 


g $b+2 


IT NOTES: 
IT A TRICKY RQUEST TO USE 


[T COMPILER OPTIMIZATION MAY NOT LET THE goto PERFORM AS IT 
SEEMS IT SHOULD 


I DEFINITELY MORE DEPENDABLE THAN COMMAND LEVEL start 


I THE SCENARIO - BACK TO OUR PROGRAM 
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SCENARIO I - MORE PROBE CONTROL 


<——_> 0 ec ee 


| 
Y $3357 0.932- 52 


check back issues 
from (specify vol: ae 
to (specify vols:num): 


Error: conversion condition by 

>user dir _dir2FSOEP>Pandolf>wkd>check_ back _issues|540 (line 48) 
onsource = "1:", onchar = ":" 

Invalid character follows a numeric field. 

system handler for error returns to command level 

r 13:57 0.469 44 level 2 


| 

| 

| 

| 

| 

| 

| 

| 

| 

| pb 

| Condition conversion raised at 

| line 48 of check _back_issues (level 7). 
| modes prompt true 

| probe: language 

| Current language is PL/I 

| probe: sc 

first_issue_volume = 

| Substr (first issue, ly titst issue delim); 
| probe: modes prompt false 

| modes prompt on 

| probe: modes prompt off 

| ov substr (first_issue, 1, first_issue delim) 

ee S 

| let f£irst_issue_ volume = "1" 

| v first issue volume 

| first_issue volume = 1 

| 
| 
| 
| 


q 
r 14:01 0.431 61 level 2 


er er ee meee mete me meme mete ees eins epee cS ramen ee SY ees cee cme es 
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SCENARIO = MORE PROBE CONTROL 


start 


Error: conversion condition by 

>user dir _dir>PSOEP>Pandolf>wkd>check_ back issues{540 (line 48} 
onsource = "l1:", Ry is =e 

Invalid character follows a numeric field. 

system handler o error returns to command level 

yr 14:01 0.257 8 level 2 


pb 

Condition conversion raised at 

line 48 of check back_ issues (level es 

4 Elrst: issue delim 

first issue_ delim = 2 

let first issue delim = 1 

vy substr Celeste issue, 1, first _issue delim) 
vd it 


G - 
r 14:03 0.244 1 level 2 


Start 

Errors cohversion condition by 

>user dir dir>FSOEP>Pandolf>wkd>check back _issues|/540 (line 43) 
onsource = “1:", onchar = ":" 

Invalid character follows a numeric field. 

system handler for error returns to command level 

r 14:03 0.235 0 level 2 

pb 

Condition conversion raised at line 48 of check back issues 
(level 7). a a 

v substr (first issue, 1, first issue delim) 

a 

goto $c 


Error: conversion condition by 
Se en eee (line ! 
50) 

onsource = "2:", onchar = ":" | 
Invalid character follows a numeric field. | 
system handler for error returns to command level | 
r 14:05 0.348 2 level 2 ! 


et em rr ee ee et et ee ee nt ee EL NR imams ine mi eet SN ene tenn ON SRY ey en Sa A NY SR Re ene ee Lee SRT SAONIRNENE ARE Seeger stent 
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CONTROL OF OUTPUT PROCESSING | 


THE PREVIOUSLY DESCRIBED value REQUEST CAN BE USED TO DISPLAY A 
NAMED STORAGE LOCATION 


I THE display REQUEST 
IT SHOWS ANY ACCESSIBLE LOCATION ON ONE OF FOUR FORMS 


T USAGE: 
display <address> <format> <count> 


ds <address> <format> <count> 


I EXAMPLES:. 
display var-one octal 2 
ds 260114430 pointer 1 


ds tmp_strng ascii 12 


I NOTES: 
FOUR MODES ARE AVAILABLE 
octal, re) 
ascii, a, character, ch, ¢ 


instruction, i 


pointer, ptr, its 
code 
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CONTROL OF OUTPUT PROCESSING 


Il THE SCENARIO 


r 14:56 0.325 16 


check_back_ issues 
from (specify vol:num): 1:1 
to (specify vol:num):1:4 


Error: illegal_ procedure condition by 

>user dir_ dir>FSOEP>Pandolf>wkd>check_ Dack_ issues$print_ record|675 
(line 96) 

(while in pll operator real _to real AEE) 

referencing stack 416363 (in process dir) 


r 14:56 1.145 34 level 2 


pb 
Condition illegal procedure raised at 
line 96 of print_record (level 8). 
sc 
total stock value = 
total Stock value + 
(issue _record.current inventory* 
TSsue. record.cost of issue); 
v cost_of issue 7 7 
cost OE. Tssue = 5 
v current ~inventory) 
current _inventory = Z3 
v total stock value 


total stock value = (invalid decimal data) 
v octal (total_ stock value) 
040040040040040040046040040 srgarauntaey 


v unspec (total stock value) 
"000100000000100000000100000000100000000100000000109000000 
LO0000000100000000100000"b 

display total stock value a 8 


display total stock value o i araseneS 
040040040040 040040040040 


g 
r 14:59 0.928 72 level 2 


eee ee ee ee tt en hee ee 
ee tr me irr mL ete rer ein rm a nei Sm SONNE cece eters Menem nme eee SO een cote Sere) = ot ee ee 
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SCENARIO III - PROGRAM MANIPUALTION 


# MORE TOOLS 


I THE where REQUEST 


I THIS REQUEST TELLS THE PROGRAMMER THE VALUES OF probe's TWO 
DEBUGGING POINTERS 


IT USAGE: 
where 
wh 
where <pointer> 


wh <pointer> 


. EXAMPLES: 
where 
wh sc 


where control 


I NOTES: 
THE TWO POINTER SPECIFICATIONS ARE: 
source, sc 
Gontroi) etl 


THE position AND use REQUESTS CHANGE THE VALUE OF THE SOURCE 
POINTER 


IT THE use REQUEST 
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SCENARIO III - PROGRAM MANIPUALTION 


] MOVES THE SOURCE POINTER TO A NEW LOCATION 


I UNLIKE THE position REQUEST, THIS DOES NOT DISPLAY THE FINAL 
LOCATION 


[ USAGE: 
use 
use <absolute line number> 
use <relative line numpber> 
use level <number> 
use <program name> 


use <character string> 


I EXAMPLES: 


use 


use +3 


use "vl = 5" 
I NOTES: THIS REQUEST CANNOT BE USED WITHOUT THE TABLE OPTION 
I] THE call REQUEST 


I INVOKES ANOTHER PROGRAM JUST AS IF IT HAD BEEN A SUBROUTINE 
CALL 


I USAGE: 


call <program name> (<Ddarameters>) 
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“SCENARIO III, ~ PROGRAM MANIPUALTION | 


IT EXAMPLE: 
call my prog (argl, arg2) 


call com_err_ (code, "from probe") 


. NOTES: 


probe PERFORMS VALUE CONVERSION AS PART OF THE CALL 
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SCENARIO III. ~ PROGRAM MANIPUALTION 


1 THE NEXT EXAMPLE 


pb check_back issues 
Using check back_ issues (no active frame). 
ps get_ record 
ger record: proc (); 
:(sk;halt) 
Beak set after line 153 


q 
C2 25404745. 250 


| 

| 

| 

| 

| 

| 

| 

| 

check back issues | 
from (specify vol:num): 1:1 : 
| 

| 

| 

| 

| 

| 

| 

| 

| 


to (specify vol:num):1:4 

get_record (line 153) 

print_ record (line 88) 

check back issues (line 65) 

simple_ command _processor|12265 

command processor_ {11070 

abbrev_75336 

Listen_ 110031 

process overseer |40055 

user_init_admin_142452 (alm) 

Stopped after line 153 of get_record. ( | 

where | 
| 


t PO GJ UT OV ~) CO WO 


line 153 in get_record (level 9) 
Control at line 153 of get_record, 
use level 8 | 
sc | 
call gets record (); | 
use level 7 | 
where | 
line 65 in check back issues (level 7) | 
Control at line 153 of get_record. | 
sc 
call print record (); | 
value issue Be | 
issue = l | 
Cc | 
| 


a ce ee ee eee eee meme Sennen nm eee tHe emmy nent) Umut ge, nen wettest lg MN Ue eh NNO aces AOD ts Seles Ae Gece aan Sreemet veomint earaaane, 
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SCENARIO II1. . PROGRAM. MANT PUALTION 


=> 
<=! 


volume 1 number i 
stocked: 23 outstanding requests: 0 cost 

\cof this issue: 

$5.00. 9 get record (line 153) 
print_record (line 88) 
check_ back _issues (line 65) 
simple_ command _processor|12265 
command _processor_ [11070 
abbrev_ T5336 
listen_ {10031 
process overseer |40055 
user_init_admin_][42452 (alm) 
Stopped after line 153 of get_ record. (level 9) 
v issue 
issue = 2 
v number of issues 
number of issues = 3 
quit 
Ee d7ti2. Le 2ie (26 


mM mp Ww & UF OV ~) 0 


te ee ee en ne men em eS ee mem OE ee ees Ot en, 
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SCENARIO IV - PROBE VARIABLES 


® MANAGING YOUR OWN VARIABLES 


IT probe ALLOWS THE PROGRAMMER TO SET UP VARIBLES KNOWN TO PROBE 
ONLY, BUT AVAILABLE FOR USE DURING ALL OF probe's PROCESSING 
(BREAKPOINTS, ETC.) 


I ALMOST LIKE HAVING A PL/I INTERPRETER 


I. THE declare REQUEST 


I USAGE: 
declare <name> <type> 


dcl <name> <type> 


bo 
bs 
ra 
2 
<4 
0 
ct 
rt 
wn 


dcl pb counter 1 fixed 
acl TOTPCT real 


dcl sum-calec comp-5 -force 


[ NOTES: 
THREE DATA TYPES ARE SUPPORTED: 
f tyed aw > 
fixed, integer, int, comp-6 
Eloat, real 


pointer, ptr 


USE THE -force CONTROL ARGUMENT TO REDEFINE A PROBE VARIABLE 
A LL ————$—$——$— LL LL AS 


ee 


IF A probe VARIABLE IS THE SAME NAME AS A PROGRAM VARIABLE, 
PREFIX THE probe VARIABLE WITH A PERCENT SIGN 
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SCENARIO IV = PROBE VARIABLES © 


I. THE list_variables REQUEST 


[ LISTS THE NAMES, DATA TYPES AND VALUES OF probe VARIABLES 


JT USAGE: 
list_variables 


- 


3% 


t- 


I. EXAMPLES: 
List_variables 


lsv 


[T ONE MORE REQUEST 


[ CONDITIONALLY EXECUTES A SET OF probe REQUESTS 


. USAGE: 


if <conditional> : (<request list>) 


] EXAMPLES: 
if a=b : (value a; halt) 


if varl = 4.56 : let var2 = 0 


I NOTES: 


CURRENT IMPLEMENTATION ALLOWS FOR ONLY SIMPLE EXPRESSION 
EVALUATION; USE THE help REQUEST TO CHECK ON NEW DEVELOPMENTS 


THE USE OF RELATIONAL OPERATORS IN THE EXPRESSION DEPENDS 
UPON THE LANGUAGE SPECIFIED TO probe 
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. SCENARIO IV - PROBE VARIABLES 


(E.G. PL/I USES =, FORTRAN USES .eqd.) 
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. SCENARIO..LV..=,,PROBE VARIABLES... 


JT AN EXAMPLE 


| | 
cr oildeie: 0,122.4 


frame). [ps get record /get record: proc (); declare 
ikea /1 list variables 
times _ get _ record called fixed’ 0 a:(let 
times _get_ record called = times get_record called + A peaks 
ioa_ ("get_ record called “i times", /s/ 
fF 


pb check back issues co check back_issues (no active 


times _get_record calle 


times ~7t. record _called);) Break set after line 153 
17:20 0.390 85 


check _back_issues 
from (specify vol:num):1:1 
to (specify vol:num):1:4 get_record called 1 times 


volume 1 number 2 
stocked: 30 outstanding requests: 2 cost of 
this issue: 
$3.00.get_record called 2 times 


Stocked: 27 outstanding requests: 0 cost of 
$3.00.get_record called 3 times 


volume lL number 4 
stocked: 20 outstanding requests: 1 cost of 
this issue: 
$3.00.get_record called 4 times 


volume l number =§ 5 


Stocked: 40 outstanding requests: 0 cost of 
this issue: 


$3.00. 
number of issues stocked: il? 
number of requests pending: 3 
total stock value: $3514.00. 


ri Ld22i 0.660 61 


re ee ee ee een re ee enim 


| 
| 
| 
| 
| 
| 
j 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
-| volume 1 number 3 
! 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
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-- SCENARIO IV - PROBE VARIABLES 


[ THE let REQUEST 


I ASSIGNS THE VALUE OF AN EXPRESSION TO A GIVEN VARIBLE 


I USAGE: 
let variable = expression 


let cross section = expression 
I EXAMPLES: 


let a =5 let array (2,i) = a-7- 5 let substr (alpha,2,3) = 
"abc" 
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_SCENARIO IV - PROBE VARIABLES 


co 1330805 156:-4 


pb check _back_issues Using check back issues ne active 
frame). ps get_ record get_ record: proc (); ps 


return; 


b: if current volume=last_ issue volume 
current number=last issue_ Tum 


q Aa " 
fo Last “desired record") 


Break set before line 175 


list variables 


times _get_record_ called fixed 4 
let times. _get_ record_ called = 0 


q 
E Tssit 0.38650 


check back issues 


from (specify vol:num): 1:3. 


ie Aunbee: 
stocked: 
chis issue: 
$3.00. volume 


this issue: 


stocked: 


cee Aspecity. vol: :num) : A236 


:call ioa_ 


° 
° 


LE 


("just positioned 


20 outstanding requests: 1 


1 number 5 


40 outstanding requests: 0 


$3.00.just positioned to last desired record 


35 outstanding requests: 4 


30 outstanding requests: 2 


volume 1 number § 
stocked: 
this issue: © 
$3.00. volume 2 number 1 
stocked: 
this issue: 
$3.00. 
number of issues stocked: 125 
number of requests pending: 
total stock value: $375.00. 


| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

ia 

i Gelune 
| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

| 

: G62. 0.79522 
| 
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"return" 


cost 


cost 


cost 


cost 


of 


P22 


_. .. SCENARIO - 


pb check back issues 


ps get_record 
get_record: proc (); 


q 
© 1613 0.245) 2 


check back issues 


volume i number > 


qd OF NO be 


from (specify vol:num): 1:3 


to (specify vol:num):1:6 


a: (let times get_record_ called = 
v times get_record called) 
Break set after line 153 


times_get_record_ called + 1; 


20 outstanding requests: 


Using check back_issues (no active frame). 


IV - PROBE VARIABLES 


of this” 


stocked: cost 
issue: 
53.0025 
volume 1 number 5 
stocked: 40 outstanding requests: 0 cost of this 
issue: 
$3.00.6 just positioned to last desired record 
volume 1 number 6 
stocked: 35 outstanding requests: 4 cost of this 
issue: 
Soe 
| volume 2 number pa 
| stocked: 30 outstanding requests: 2 cost of this 
| issue: 
| 9300s 
| 
{| mumber of issues stocked: 125 
| number of requests pending: a 
| total stock value: S375:2005 
l- tee la Eel OS 6 | 
| 
| | 
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SCENARIO IV - PROBE VARIABLES. 


a NS a | NS 


pb check back issues 

Using check_ back_ issues (no active frame). 

st 

Break exists after line 153 in check back issues 
Break exists before line 175 in check_back_issues 
ps 153 

get_record: proc (); 

st at 153 


Break exists afte line 1 
times get record called + 


te oe ee ~k wees 


53 :iet times get_ record called = 
l; v times _get_ record_ called 


aly 


az (let times get_record_called = 
l;call ioa_ ("“get_record called “d 
times _get_record called) ) 
Break set after line 153 


times _get_record called + 
times", 


ps l 

check back issues: 
= proc; 

a 


wb eak See after ine). re 
-aslet times Mget: record. called =. 0) 
Break set after line 1” — 


8:17 0.456 2 
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TOPIC V 


MULTICS USER RING RUNTIME STRUCTURES. 
Pre COCUCEIO Ny. ore ees ae Ges Ven idee Me 
Supervisor Segments .....«. e« 
The Stack Segment - stack nn... 
The area.linker Segment ..... 

Getting Space for Program 


e 


Var 


@ 


e 


oa 


2 


iables 


Topic V MULTICS USER-RING RUNTIME STRUCTURES Toric Vv" 


OBJECTIVES: 


Upon completion of this toric, students should be able tos: 


1. Describe some of the ways in which processes can be 
inadvertently destroved. 


Cw J TA nw mie | or  & me fs wn me Hk oe oe im I + be om Lm FT om anime MRBawr nme em Pe me oe) om me Pom ce ae 
a a MoS. LAS ilo TMUSEUeULUTIS wr Lito TUea LWW tia ble ee © ee OE eee © Oe Oe ae ee 2 
sesments: 
dseag 
kst 
pds 
stack.1 - stack_7 (as aprropriate) 


hii quecarea et ajeer i. 
3. Describe the format of the followins structures: 


linkage offset table (LOT) 
internal static offset table (ISOT) 


reference _name_table (RNT) 


4. Name the sections of a standard Multics obJect sesment and 
give the functions of each. 


Multics V—-4 _ Fe 


INTRODUCTION _ 


® INTRODUCTION 


I THERE IS NO CENTRALIZED LOCATION FOR ALL PROGRAM SUPPORT TABLES 
AND DATA IN MULTICS 


I NATIVE MULTICS USES SEVERAL SEGMENTS TO MANAGE RUNTIME 
INFORMATION 


MOST ARE FOUND IN THE PROCESS DIRECTORY 


4 


I THE PROCESS DIRECTORY IS CREATED FOR A USER AT LOGIN TIME 
I IT IS PART OF THE HIERARCHY, JUST AS THE HOME DIRECTORY IS 


I. IT IS. GIVEN A SHRIEK NAME. AS ITS IDENTITY 
1 THESE TABLES ARE MODIFIABLE BY PROGRAMS IN A PROCESS 


[ THEIR MISUSE IS THE MAIN CAUSE OF PROCESS FAILURE 


of To Be Reproduced il F2l 


INTRODUCTION 


r 04:38 0.163 1 

pd 

>process dir_dir>!BXNCwXCBBBBBBB 
r 04:38 0.044 0 


cwd [pd] 
r 04:38 06.047 6 


List 


Segments = 7, Lengths = 0. 


rew Q !BBBUJLFKcGzxlDq.temp.0326 
rew 0 !BBBJLFKcGxXPLpJ.area.linker 
rew Q stack 4 
re 0 pit 

0 pds 

0. kst.. . 

QO. dseg. | 


cr 04:38 0.196 0 


cee es cee ey een ee ene ees re ee es ee Ge ms ee SD EE eee cen oe 
_— : ' 
at em eee ce eee a es ee ne Se eee ee mee cine Sm meee ne SE ne ee ees 
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' SUPERVISOR SEGMENTS 


® dseg 


T DESCRIPTOR SEGMENT 


I RESIDES IN RING 0 


[ USED BY THE HARDWARE TO CALCULATE MEMORY ADDRESSES 


| 2S. NOT: ACCESSIBLE TO THE USER 


IT KNOWN SEGMENT TABLE 


I] RESIDES IN RING 0 


§ IS NOT ACCESSIBLE TO THE USER 
I IS USED INDIRECTLY BY VIRTUAL MEMORY OPERATIONS 


I IS AN ARRAY OF BLOCKS, EACH BLOCK CONTAINING INFORMATION 
ABOUT EACH SEGMENT THE PROCESS IS CAPABLE OF REFERENCING 
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SUPERVISOR SEGMENTS | 


I FOR A SEGMENT TO BE USED IN A PROCESS (E.G. PRINTED, EDITED, 
EXECUTED) IT MUST HAVE AN ENTRY IN THE kst 


[ IF A SEGMENT HAS AN ENTRY IN THE kst IT IS CONSIDERED "KNOWN" 


iB 
ue) 
(2 
tA 


I PROCESS DATA SEGMENT 


I RESIDES IN RING 0 


“I CONTAINS MANY THINGS . THE.SUPERVISOR. WANTS TO KNOW ABOUT. YOUR ~ 
“" “PROCESS: 7 


IT YOUR PROCESS ID 

I YOUR gone ID 

1 PROCESSOR INFORMATION FOR eAUL AND CONDITION PROCESSING 
I RING INFORMATION 


[T MORE 


I NOT ACCESSIBLE TO THE USER 
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- SUPERVISOR SEGMENTS 


SEG 344 


KSTE 3OR 
SEGMENT 


SEG 343 


KSt dseg 


|FAULT DATA | 


DATA CELLS 
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‘THE STACK SEGMENT - STACK N_ 


USER STACK 


I FUNCTION 


et 


I 


IS THE BACKBONE OF THE MULTICS PROGRAMMING ENVIRONMENT 


USED TO DEFINE THE REST OF THE PROGRAMMING ENVIRONMENT 


[. THE STACK IS DIVIDED INTO TWO FUNCTIONAL PARTS 


AT THE BEGINNING OF THE STACK IS THE STACK HEADER 


‘THE READER CONTAINS POINTERS OF ALL THE OTHER TABLES USED’ 


AT SOME POINT INTO THE STACK SEGMENT (DEPENDING ON THE STACK 
ITSELF) ACTIVATION FRAMES WILL BE FOUND 


BACH FRAME CONTAINS INFORMATION ABOUT VARIABLES OF A 
CURRENTLY ACTIVE (CALLED, BUT NOT YET RETURNED) PROGRAM 


I THE SIZE OF THE STACK IS NOT PREDICTABLE, BECAUSE AS PROGRAMS 
ARE CALLED AND RETURN THE STACK WILL GROW AND SHRINK 
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THE STACK SEGMENT - STACK N 


TO NEAT 
FRAME ie 


FOINTER 
TO LINKS 


POINTER 
TO PROGRAM 
POINTER 


TO LINKS 


S_ 


POINTER 


NTT mi ™ DPRAMP 
POINTER TO FIRST FRAME TO PROGRAM 


NULL 
POINTER 
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' THE STACK SEGMENT ~ STACK N™ 


I IS USED BY THE DYNAMIC LINKER AND BY PROGRAMS TO FIND THEIR 
LINKAGE INFORMATION 


JT IS QUITE SIMPLY AN ARRAY OF ONE WORD ADDRESSES SHOWING WHERE 
VARIOUS LINKAGE SECTIONS ARE 


[T TO FIND OUT WHERE THE LINKAGE INFORMATION FOR A PROGRAM (CALL 
IT foo), FIRST OBTAIN ITS SEGMENT NUMBER 


[I COUNT UP THAT MANY WORDS FROM THE BEGINNING OF THE LOT AND 
THE WORD AT WHICH YOU ARRIVE CONTAINS THE ADDRESS OF f00'S 
LINKAGE INFORMATION 


[THE “LOT: HAS” AN“INITIAL SIZE OF 512 WORDS AND’ IS ACTUALLY 
OVERLAID UPON THE BEGINNING OF THE STACK | 


@ THE INTERNAL STATIC OFFSET TABLE - THE ISOT 


I THE ISOT CONTAINS ONE WORD ADDRESSES OF THE STATIC SECTIONS OF 
ALL THE ACTIVE PROGRAMS 


I IT TOO IS AN ARRAY OF THESE ADDRESSES 


I TO FIND THE LOCATION OF SOME PROGRAM'S STATIC SECTION, ONE 
COUNTS UP ITS SEGMENT NUMBER WORTH OF WORDS AS IN THE LOT 
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I THE SIZE OF THE ISOT IS ALSO 512 WORDS LONG AND IT IS FOUND 
RIGHT AFTER THE LOT ON THE STACK 


I BECAUSE OF THE LOT AND ISOT, THE FIRST STACK FRAME USUALLY 
BEGINS RIGHT AFTER THE ISOT 


1S) 
1 
\O 
ny 
N 
fan 
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THE STACK SEGMENT -“STACK N 


POINTER 
POINTER 
| POINTER 
POINTER 
POINTER 
| POINTER 


FIRST 
STACK 
FRAME 


POINTER 
POINTER 


POINTER 
POINTER 
POINTER 


D 
| POINTER 
POINTER 


Lad 


POINTER 
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THE AREA.LINKER SEGMENT 


® THE COMBINED LINKAGE AREA 


I AS WILL BE SEEN IN DYNAMIC LINKING, SOME INFORMATION FROM AN 
OBJECT SEGMENT NEEDS TO BE COPIED OUT INTO A WRITEABLE AREA 


I THE COMBINED LINKAGE AREA IS ONE OF THE TWO AREAS THAT HOLD THIS 
COPIED DATA 


I THE COMBINED LINKAGE AREA IS A PL/I TYPE AREA - A MANAGED POOL 
OF STORAGE FOR ALLOCATING AND FREEING DATA 


I HISTORICALLY THE COMBINED LINKAGE AREA WAS A PHYSICALLY SEPARATE 
AREA APART FROM OTHER RUNTIME AREAS. . 


NOW IT IS JUST A "SYNONYM" FOR THE area.linker 


—t 


4 


@ THE COMBINED STATIC AREA 


I MODIFIABLE STATIC DATA IS MAPPED OUT IN THE OBJECT SEGMENT WHEN 
IT IS CREATED, BUT NEEDS TO BE MODIFIED 


[T TO PREVENT THE MODIFICATION OF THE OBJECT ITSELF, THE STATIC 
DATA TEMPLATE IS COPIED FROM THE OBJECT TO THE COMBINED STATIC 
SECTION (COMBINED BECAUSE IT IS COMBINED WITH THE STATIC 
SECTIONS OF OTHER PROGRAMS) 
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| THE AREA.LINKER SEGMENT 


| 
| 


i 


VERSION 
TWO 
AREA 
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I 


I 


THE AREA. LINKER SEGMENT 


THE COMBINED STATIC AREA IS AGAIN A PL/I TYPE AREA 


THE COMBINED STATIC AREA IS ANOTHER SYNONYM FOR THE area.linker 
SEGMENT 


® THE REFERENCE NAME TABLE - THE RNT 


THE 


I 


4 


REPOSITORY FOR A SET OF ATTRIBUTES CALLED REFERENCE NAMES 


A REFERENCE NAME IS AN ATTRIBUTE OF A SEGMENT FOR PROGRAMMING 
PURPOSES 


‘A REFERENCE NAME EXISTS ONLY WITHIN A PROCESS - IT IS NOT 


PERMANENT 
IT IS A SYNONYM FOR A SEGMENT THAT IS THE OBJECT OF A SEARCH 


IT MAY OR MAY NOT BE RELATED TO THE ACTUAL NAME OF THE 
SEGMENT 


IT. IS CREATED IMPLICITLY OR EXPLICITLY 


‘IT WHEN A PROGRAM IS CALLED IT IS GIVEN A REFERENCE NAME 


] WHEN THE RING 0 initiate PROGRAM IS CALLED (THROUGH A 
GATE, OF COURSE) 


THE RNT ALSO MAINTAINS THE ASSOCIATION BETWEEN A REFERENCE NAME 
AND THE SEGMENT NUMBER OF A SEGMENT 
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— 


‘THE AREA.LINKER SEGMENT | 


THE RNT IS IN THE FORM OF A RATHER INVOLVED SERIES OF LINKED 
LISTS 
[] THE RNT IS DEFINED BY A HEADER WHICH CONTAINS TWO HASH 


TABLES, ONE FOR SEGMENT NUMBERS AND ONE FOR REFERENCE NAMES 
I EACH ENTRY IN THE RNT IS IN TWO LINKED LISTS - A REFERENCE 
NAME LIST AND A SEGMENT NUMBER LIST 


THE RNT RESIDES IN THE MIDDLE PORTION OF THE area.linker SEGMENT 


IT MANAGES ITS OWN AREA IN THIS SEGMENT 


@ THE USER’ FREE AREA 


I 


USED FOR ALLOCATING CONTROLLED A!:D SOME BASED VARIABLES, FOR 
FORTRAN -COMMON AND FOR COBOL DATA 


OBVIOUSLY, BY NOW, IT IS A PL/I AREA 


THE USER FREE AREA ALSO IS A "SYNONYM" FOR THE area.linker 
SEGMENT 


TO RUN A PROGRAM THE USER MUST 


I CREATE AN OBJECT SEGMENT ACCEPTABLE TO THE MULTICS LINKERS 


T CALL THE PROGRAM 
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THE AREA .LINKER SEGMENT © 


SYSTEM 


FREE AREA 


STACK (get_system free _area_) 


REGISTERS 


CALLING HISTORY SASED DATAC 
chat 


he ad 
COMBINED STATIC AREA AUTOMATIC 
INTERNAL 
STATIC : 
SECTION me : 
. STACK 
HEADER 


yuMZ2ewKoOn 


ASSIGNED LINKAGE AREA 
(nes Sassign_ linkage) 


EXT. STATIC & 
COMMON BLOCKS - 
PER PROCESS 
: | LINKAGE CONTROLLED | CONTROLLED 
|g | INTERNAL {| EXTERNAL | 
tir 
Nig 
: a RUN UNIT | | 
INFO >| COBOL PROGRAM 
sii cobol control data ic # DATA 
E 2 vata jC _ 
; | ext ,=_# P | 
pro P _it- 0 
at | = = i | BASED DaTa- | [ sase0 DATA- | 
el N NO AREA IN 1/0 BUFFER 
A lg T aaa i eee 
E 
R 
S 
DIRECTORY 
ane PATHNAMES 
| EXTERNAL STATIC 
grog AND COMMON BLOCKS- 
| OBJECT PERMANENT 
prog.pll PROGRAM 
SOURCE ext 
PROGRAM 
prog 
prog.pll 
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WRIA CS 


0109 pa 


a 


THE AREA.LINKER SEGMENT | 


bomey 
my 
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© 
ae 
Hae) 
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call prog$entry (); 
I OR, BY INVOKING IT AT COMMAND LEVEL 
progSentry 
I THE COMMAND LEVEL INVOCATION DOES NOT CALL IN THE DYNAMIC 
LINKER, WHILE THE CALL STAEMENT MAY 


I THE OBJECT SEGMENT FUNCTIONS TO 


[I PROVIDE INSTRUCTIONS AND DATA IN THE MACHINE'S LANGUAGE 
I INSTRUCTIONS ARE CURRENTLY IN L68 MACHINE CODE 


[ THE DATA IS PROVIDED FOR THE MULTICS LINKER, PRELINKER, 
BINDER, AND DEBUGGERS 


— “COMPOSED .OF 7 SECTIONS 
i TEXT SECTION 
I DEFINITION SECTION 
I LINKAGE SECTION TEMPLATE 
I STATIC SECTION TEMPLATE (OPTIONAL) 
I SYMBOL SECTION 
I OBJECT MAP 


I OBJECT MAP POINTER 
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OndecT Se 6haT 
__. THE-AREASLENKER SEGMENT 


- a= 
EEO 


1 TEXT SECTION 


[T PURE PART OF AN OBJECT PROGRAM 


I CONTAINS: 
I INSTRUCTIONS (NO SELF-MODIFYING INSTRUCTIONS) 
I ENTRY SEQUENCES 
[ READ-ONLY DATA 
Teloirve Lormntots 


. DEFINITION SECTION 


IT NONEXECUTABLE, READ-ONLY SYMBOLIC INFORMATION 
IT USED FOR DYNAMIC LINKING 


I . USED FOR SYMBOLIC DEBUGGING | 


I CONTAINS 
I DEFINITIONS | 
J OFFSETS OF NAMED ENTITIES IN TEXT AND OTHER SECTIONS 
I 


DEFINITION HASH TABLE (OPTIONAL) TO EXPEDITE THE LINKER'S 
SEARCHES 


[T SYMBOLIC NAMES OF EXTERNAL REFERENCES 
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THE AREAVLINKER SEGMENT 


I LINKAGE SECTION TEMPLATE 


I INITIAL CONTENTS OF THE IMPURE, NONEXECUTABLE PART OF A 
PROGRAM 


J USED FOR DYNAMIC LINKING 
J CONTAINS 


I UNSNAPPED LINKS TO EXTERNAL REFERENCES 


I DATA ALLOCATED ONCE PER-PROCESS (INTERNAL STATIC DATA) 


1 COPIED INTO COMBINED LINKAGE AREA IN THE PROCESS DIR WHEN 
OBJECT SEGMENT IS FIRST REFERENCED 
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THE AREA.LINKER SEGMENT 


I STATIC SECTION TEMPLATE 


[ THE INITIAL CONTENTS OF IMPURE, NONEXECUTABLE DATA FOR OBJECT 
PROGRAM 


DATA IS 


4 


I ALLOCATED ONLY ONCE PER PROCESS 


I INITIALIZED ONLY ONCE PER PROCESS 


IT USUALLY INCLUDED AS PART OF LINKAGE SECTION UNLESS THE 
~separate static CONTROL ARGUMENT IS USED WHEN COMPILING THE 
PROGRAM 


J COPIED INTO COMBINED STATIC AREA IN PROCESS DIR WHEN OBJECT 
SEGMENT IS FIRST REFERENCED 
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THE AREA.LINKER SEGMENT 


I SYMBOL SECTION 
I IS PURE 


IT CONTAINS INFORMATION NOT BELONGING IN OTHER SECTIONS 


I USED FOR SYMBOLIC DEBUGGING 


[ INFORMATION DOCUMENTING CREATION OF OBJECT PROGRAM 
I RELOCATION INFORMATION 
I SOURCE SYMBOL NAMES AND STORAGE LOCATIONS (PRESENT ONLY IF 
~table OPTION SPECIFIED) 
[ NOTE: IN THE CASE OF BOUND OBJECT, THIS SECTICN MIGHT BE 


FURTHER STRUCTURED INTO A THREADED LIST OF VARIABLE LENGTH 
SYMBOL BLOCKS | , es ns 
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THE AREA.LINKER SEGMENT 


[ OBJECT MAP 


I DEFINES THE LOCATION (OFFSET) AND LENGTH OF OTHER SECTIONS 


I] DEFINES OBJECT SEGMENT FORMAT 
I SINGLE (UNBOUND) OBJECT PROGRAM, OR 


I SEVERAL OBJECT PROGRAMS, BOUND TOGETHER 


I OBJECT MAP POINTER 


IT AN 18-BIT OFFSET IN THE UPPER HALF WORD OF THE LAST WORD IN 
THE OBJECT SEGMENT 


{ GIVES LOCATION OF OBJECT MAP, RELATIVE TO BASE OF OBJECT 
SEGMENT 


J FOUND USING THE BIT COUNT 
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THE. AREA.LINKER SEGMENT - 


ase 


DEFINITIONS 
LINKAGE 
SECTION 


I STATIC 
SECTION 


MBOL 


oy 
SECTION 


| 
: 


ft f 


} OBJECT MAP | 
pbve ct 
ma P 
Pp. mar hy 
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THE AREA. LINKER SEGMENT 


GETTING SPACE FOR PROGRAM VARIABLES 


8 CONSTANTS 


JT CONSTANT DATA VALUES, KNOWN ONLY TO ONE PROGRAM 


I DECLARATION 


I PL/1: del con fixed bin internal static options(constant) 
initial(3); 


[T COBOL: CONSTANT SECTION. 
77 CON; PIC IS 99; VALUE IS 3. 


I FORTRAN: parameter con=3 _ 


rH 
rt 
© . 
O) 
ys 
| 
re 
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J] ALLOCATED AND INITIALIZED 


JT ONCE BY THE COMPILER, WHEN THE SOURCE PROGRAM IS COMPILED 


I FREED 


[T NEVER 
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THE AREA.LINKER SEGMENT 


GETTING SPACE FOR PROGRAM VARIABLES 


ATES = ROE EOE ei 


INTERNAL STATIC 


4 


PER PROCESS DATA, KNOWN ONLY TO ONE PROGRAM 


DECLARATION 
I PL/1: declare is internal static; 


J FORTRAN: save is 


LOCATION 


J IN. INTERNAL. STATIC SECTION OF PRCOREy: WHICH IS THEN COPIED 
-TO [unique].area.linker — ve . 


I NOTE: SUCH VARIABLES CAUSE THE SIZE OF THE OBJECT TO GROW 


ALLOCATED AND INITIALIZED 


I FIRST TIME OBJECT SEGMENT IS CALLED IN THE PROCESS BY COPYING 
OBJECT'S LINKAGE SECTION (OR SEPARATE STATIC SECTION) 


FREED 


IT WHEN PROCESS TERMINATES, OR WHEN OBJECT SEGMENT IS EXPLICITLY 
TERMINATED (terminate COMMAND) 
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_ THE AREA.LINKER SEGMENT 


GETTING SPACE FOR PROGRAM VARIABLES 


# AUTOMATIC 


PER PROGRAM-ACTIVATION DATA, KNOWN ONLY TO ONE PROGRAM 


m4 


J DECLARATION 


I PL/1l: declare a automatic; 


I FORTRAN: automatic a 


LOCATION 


ei 


T "ALLOCATED" -IN STACK FRAME WHEN FRAME IS PUSHED 


T ALLOCATED AND INITIALIZED 


I EACH TIME PROGRAM IS CALLED 


I FREED 


IT WHEN PROGRAM RETURNS 
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‘THE AREA.LINKER SEGMENT: 


GETTING SPACE FOR PROGRAM VARIABLES 


3 EXTERNAL STATIC - PER PROCESS 


I PER PROCESS 
SEGMENTS IN THE PROCESS DIRECTORY 


I DECLARATION 
£ “PEL: 


I FORTRAN: common b,c 


common /e/b,c 


I LOCATION 


T ALLOCATED IN USER FREE AREA 


J ALLOCATED AND INITIALIZED 


I WHEN FIRST REFERENCED 


I FREED 
Il WHEN PROCESS TERMINATES, 
reset external variables AND 
COMMANDS ) 
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DATA, SHARED BETWEEN PROGRAMS, 


declare e external static; 


STORED IN TEMPORARY 


OR EXPLICITLY (SEE 
delete external variables 


P22 


THE AREA.LINKER SEGMENT 


GETTING SPACE FOR PROGRAM VARIABLES 


® EXTERNAL STATIC - PERMANENT 


[ PERMANENT DATA, SHARED BETWEEN PROGRAMS, STORED IN USER-SUPPLIED 
SEGMENTS 


I DECLARATION 


I PL/1: declare extS external static, 
extSe external static; 


I] FORTRAN: common /ext$/b,c 
common /extSe/b,c 


LOCATION 


m4 


I IN PERMANENT SEGMENT ext, FOUND BY LINKER (USING OBJECT 
SEARCH RULES) 


[ SEGMENT MUST EXIST PRIOR TO EXECUTION 


I ALLOCATED AND INITIALIZED 


[ WHEN SEGMENT ext IS CREATED 


I EXPLICITLY BY DELETING THE CONTAINING SEGMENT 
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THE AREA.LINKER SEGMENT 


GETTING SPACE FOR PROGRAM VARIABLE 


@ CONTROLLED STORAGE - INTERNAL 


J EXPLICITLY-ALLOCATED DATA, KNOWN TO ONE PROGRAM 


an) 
) 
ty 
Q 
Cc 
Wi 
a 
ed 


IT PL/1: del ¢ controlled int; /* int is default */ 
allocate c; 
allocate ec; 


[T LOCATION 


I ALLOCATED iN USER FREE AREA IN [unique].area.linker | 


[ ALLOCATED AND INITIALIZED 


[T EXPLICITLY BY PL/1 allocate STATEMENT 


I FREED 


I EXPLICITLY BY PL/1 free STATEMENT - 
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_THE AREA.LINKER SEGMENT 


GETTING SPACE FOR PROGRAM VARIABLES 


® CONTROLLED STORAGE - EXTERNAL 


J] EXPLICITLY-ALLOCATED DATA, SHARED BETWEEN PROGRAMS 


I] DECLARATION 


I PL/1: declare ce controlled external; 
allocate ce; 


I LOCATION 


IT ALLOCATED IN USER FREE AREA IN funique] .area.linker 


JT FREED 


IT EXPLICITLY BY PL/1 free STATEMENT 
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. THE AREA.LINKER SEGMENT 


‘GETTING SPACE FOR PROGRAM VARIABLES 


® BASED ~ IN AN AREA 


IT EXPLICITLY-ALLOCATED DATA, KNOWN ONLY TO ONE PROGRAM, QUALIFIED 
BY A LOCATOR 


I DECLARATION 


I PL/1: dcl area area, 
b based(p), 
Pp ptr; 
allocate b in (area); 


I LOCATION 


I DEPENDS WHERE THE USER SPECIFIES THE AREA TO BE (PERHAPS THE 


SYSTEM FREE AREA SUPPLIED BY INVOKING get_system_ free area_} 


I ALLOCATED AND INITIALIZED 


I EXPLICITLY BY PL/1 allocate STATEMENT 


I FREED 


[ EXPLICITLY BY PL/1 free STATEMENT 
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THE AREA.LINKER SEGMENT 


GETTING SPACE FOR PROGRAM VARIABLES 


@ BASED - NO AREA 


EXPLICITLY~ALLOCATED DATA, KNOWN ONLY TO ONE PROGRAM, 
BY A POINTER 


4 


IT DECLARATION 


I PL/1: declare b based(p), 
(p,pl) ptr; 
allocate 6b; 
allocate b set(pl); 


I LOCATION 


I IN USER FREE AREA WITHIN [unique].area.linker 
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IT EXPLICITLY BY PL/1 allocate STATEMENT 


I FREED 


J EXPLICITLY BY PL/1 free STATEMENT 
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QUALIFIED 


THE AREA.LINKER SEGMENT 


GETTING SPACE FOR PROGRAM VARIABLES 


8 BASED - IN AN I/O BUFFER 


I EXPLICITLY-ALLOCATED DATA, KNOWN ONLY TO ONE PROGRAM, QUALIFIED 
BY A POINTER 


J DECLARATION 


I PL/1: declare b based(p), £ file; 
read file(f) set(p); 
locate b file(f£) set(p); 


I LOCATION 
IT IN. -AN I/O BUFFER. . ALLOCATED BY .PL/L.IN .USER FREE AREA IN - 


(unique]-.area.linker 


[ ALLOCATED 


I EXPLICITLY BY PL/1 read (WITH set OPTION) OR locate STATEMENT 


I INITIALIZED 


I BY locate STATEMENT 


I FREED 


IT BY SUBSEQUENT I/O OPERATION ON THE FILE 
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THE AREA.LINKER SEGMENT 


GETTING SPACE FOR PROGRAM VARIABLES 


LEELA «= SEERA CERES 86 SRR EEE 


@ COBOL DATA 


I INTERNAL STATIC-LIKE DATA, KNOWN ONLY TO ONE PROGRAM 


J DECLARE 


T COBOL: WORKING SECTION. 
/7-CB PIC 15 -99.. 


I LOCATION 


if ALLOCATED IN USER FREE AREA 
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] WHEN THE PROCESS OR COBOL RUN UNIT TERMINATES, OR EXPLICITLY 
(BY A cancel _cobol_ program COMMAND OR A CANCEL STATEMENT) 
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= Topic VI | | | MULTICS DYNAMIC LINKING | Topic VI 
OBJECTIVES: 

Upon completion of this topic, students should be able to: 

1. Compare conventional linkins with Multics dynamic Linkins. 

2. List the functions performed by the Multics dynamic linker 


3. Trace the oreration of the dynamic linker from the time it 
first encounters an unsnarpred link until it resolved the 
linkage fault. 


4. Discuss the side-effects of dynamic linking and some of the 
dangers related to it. 


3. Explain what harprens when binding occurs and why it can be 
used to. sreat. advantage, 
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INTRODUCTION 


® LINKING 
I A LINKER IS BASICALLY A POST COMPILER 


[ SYMBOLIC REFERENCES TO LOCATIONS NOT WITHIN THE OBJECT NORMALLY 
CAUSE THE TRANSLATOR TO PRINT AN ERROR MESSAGE 


J TELLING THE COMPILER OR ASSEMBLER THAT A SYMBOL IS EXTERNAL IS 
JUST A FUDGE SO THAT IT WON'T COMPLAIN 


I THE TRANSLATOR STILL CAN'T CALCULATE AN ADDRESS, SC IT BUILDS A 
STRUCTURE TELLING WHAT IT WAS LOOKING FOR 


TI UIT -iS°"THE JOB. OF ~ THE LINKER: TO‘ “RESOLVE ALL’ “THESE UNLINKED 
"REFERENCES a | > ee 
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INTRODUCTION 
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INTRODUCTION 


® THE TRADITIONAL LINKER 


I 


T 


= 


PHILOSOPHY 

I LINKING MUST BE DONE BEFORE THE PROGRAM RUNS 

I LINKING IS ASSOCIATED WITH LOADING - PLACING THE PROGRAM IN 
MEMORY 

I ALL EXTERNAL REFERENCES MUST BE PRESENT AT LINKING TIME 

I THE LINKER PRODUCES A "LOAD UNIT" OR "BOUND UNIT" - ABLE TO 
BE PLACED IN MAIN MEMORY WITH ALL ADDRESSES RESOLVED 

I THE LOAD UNIT IS THEN RUN BY THE USER 

LIMITATIONS 

I THE LINKER IS THE LAST STEP IN ADDRESS RESOLUTION - IF IT 
CAN'T DO IT, NOTHING CAN 

I BECAUSE TRADITIONAL LINKING IS ASSOCIATED WITH REAL MEMORY, 
ALL PROGRAMS HAVE TO BE PRESENT TO GET A SPOT IN THE BOUND 
UNIT, AND HENCE THE MEMORY 

I IF THE LINKER CAN'T RESOLVE A LINK, THE LINKING FAILS 

I CHANGING ONE PROGRAM IMPLIES LINKING EVERYTHING OVER AGAIN 

I SUBSTITUTING A PROGRAM MID-EXECUTION IS IMPOSSIBLE 
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INTRODUCTION 
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INTRODUCTION 


THE DYNAMIC LINKER 


I 


I 


PHILOSOPHY 


IN AN OPERATING SYSTEM WITH MANY (100 PLUS) SEGMENTS, LOADING 
AND RELOCATION BECOME PART OF THE JOB OF THE HARDWARE, NOT 
THE SOFTWARE 


RESOLVING REFERENCES BECOMES EASIER BECAUSE THE TRANSLATOR 
GENERATES ADDRESSES RELATIVE TO THE BASE OF THE PROGRAM, AND 
HENCE THE SEGMENT 


THE JOB OF THE LINKER HAS BEEN REDUCED TO FINDING A SEGMENT 
NUMBER AND AN OFFSET WITHIN THE SEGMENT TQ COMPLETE THE 
EXTERNAL REFERENCE 


“ WITH RELOCATION ALREADY TAKEN CARE OF, AND LINKING REDUCED TO’ ” 
THE ‘CALCULATION ‘OF TWO’ NUMBERS, LINKING CAN BE POSTPONED | 


UNTIL THE EXTERNAL REFEENCE IS MADE 


ALTHOUGH DYNAMIC LINKING IS POSSIBLE USING A REAL MEMORY, 
UNSEGMENTED MACHINE, THE BY-PRODUCTS OF SEGMENTATION MAKE IT 
WORTH WHILE TO IMPLEMENT 


WITH THE DRUDGERY OF PRE-LINKING TAKEN AWAY FROM THE 
PROGRAMMER, S/HE CAN SPEND MORE TIME WORRYING ABOUT THE 
PROGRAM, AND NOT ABOUT THE MEMORY MANAGEMENT 


LIMITATIONS 


EXCESSIVE USE OF DYNAMIC LINKING CAN SLOW THE OVERALL SYSTEM 
THROUGHPUT 


BY GIVING THE JOB OF LINKING TO THE OPERATING SYSTEM, THE 
PROGRAMMER HAS LESS SAY OVER WHICH VERSION OF A PROGRAM IS TO 
BE USED 
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INTRODUCTION 


[ ADVANTAGES 


IT PROGRAMS ARE EXECUTEABLE WITHOUT ALL EXTERNAL REFERENCES 
BEING PRESENT - ONE NEED ONLY WRITE AND DEBUG A SMALL PORTION 
AT A TIME ike 


[ SUBSTITUTING SUBROUTINES CAN BE DONE AT RUNTIME WITH LITTLE 
EFFORT AND COST TO THE OPERATING SYSTEM 


I EXTERNAL REFERENCES THAT ARE AVOIDED BECAUSE OF TRANSFERS 
WITHIN A PROGRAM NEVER HAVE TO BE RESOLVED 


Not To Be Reproduced 6-6 F21 


INTRODUCTION 


DYNAMIC LINKER 
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MULTICS COMPILER CONVENTIONS 


® EXTERNAL REFERENCES 


I ALL STANDARD MULTICS COMPILERS GENERATE THE SAME TYPE OF LINK 
THAT RELATES TO BOTH PRELINKING (BINDING) AND DYNAMIC LINKING 


IT IS A REPOSITORY FOR THE EXTERNAL ADDRESS 


[T CONTAINS INFORMATION TELLING ABOUT THE NAME OF THE EXTERNAL 
REFERENCE, INTERNAL LOCATIONS, WHETHER OR NOT TO CREATE IT IF 
NOT FOUND, ETC. 


_[ INITIALLY CREATED IN THE LINZAGE SECTION OF THE OBJECT SEGMENT 
I ONE FOR EACH EXTERNAL REFEREVCE 


T IS TWO WORDS LONG 


[ MAY BE UNSNAPPED 
I THE END OF THE FIRST WORD CONTAINS THE “FAULT-TRAP 2" CODE 
I THE REST OF THE LINK CONTAINS ADDRESSES OF INFORMATION FOR 
THE LINKERS 
T MAY BE SNAPPED 


I THE END OF THE FIRST WORD CONTAINS THE "ITS" CODE - 
INDICATES A VALID MULTICS POINTER 


Not To Be Reproduced 6-8 B21 


MULTICS COMPILER CONVENTIONS 


I] THE FIRST HALF OF THE FIRST WORD CONTAINS THE SEGMENT 
NUMBER OF THE EXTERNAL REFERENCE 


I THE FIRST HALF OF THE SECOND WORD CONTAINS THE OFFSET 
WITHIN THE SEGMENT OF THE EXTERNAL REFERENCE 


IT CONTAINS ALL THE LINKS A PROGRAM NEEDS 


I IS COPIED OUT OF THE OBJECT SEGMENT BEFORE THE OBJECT IS 
EXECUTED 


‘I IS MERGED INTO THE COMBINED LINKAGE AREA. 
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MULTICS COMPILER CONVENTIONS 


ORIGIN 
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MUTLICS OPERATING SYSTEM SUPPORT. 


® MANAGEMENT OF EXTERNAL REFERENCES 


[. WITH FEW EXCEPTIONS, COMPUTERS EXPECT ADDRESSES TO BE IN NUMERIC 
(BINARY) FORM 


I THE 


MULTICS HARDWARE CURRENTLY FOLLOWS THIS ARCHITECTURE 


{ THE DESIGNERS OF MULTICS DECIDED THAT IT WAS TIME TO MOVE AWAY 
FROM SOFTWARE ALSO USING NUMBERS 


ig 


PROGRAMMERS STOPPED PROGRAMMING IN BINARY MACHINE LANGUAGE 
YEARS AGO, USING A MNEMONIC ASSEMBLY LANGUAGE 


_ HUMANS, REMEMBER.AND MANIPULATE WORDS. MORE EFFICIENTLY, THAN 
NUMBERS” 


wu 
be 


THE HARDWARE LOCATIONS OF DATA MAY CHANGE, SUT THE NAME WILL 
REMAIN THE SAME 


SOFTWARE TECHNOLOGY NOW ALLOWS SYMBOLIC NAMES TO BE 
AUTOMATICALLY MANAGED CHEAPLY 


I MULTICS SUPPORTS SYMBOLIC (VIRTUAL) ADDRESSES FOR POTENTIALLY 
ALL THE DATA ON THE SYSTEM 


it 


SPECIFIED BY A TWO COMPONENT NAME IN THE FORM OF 
alpha$Sbeta 
[T alpha IDENTIFIES A SEGMENT 


IT beta IDENTIFIES A LOCATION WITHIN THE SEGMENT 
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“MUTLICS OPERATING SYSTEM SUPPORT 


IT MULTICS WORRIES ABOUT THE HARDWARE NUMBER ASSOCIATED WITH 


alpha 


I MULTICS WORRIES ABOUT THE HARDWARE NUMBER ASSOCIATED WITH 
beta 


I THE PROGRAMMER IS CONCERNED ONLY WITH REMEMBERING AND 
MANAGING THE ENTITY alphaSbeta 


[. THIS SCHEME IS IMPLEMENTED EVEN AT THE MULTICS ASSEMBLY 
LANGUAGE LEVEL 


T MULTICS MANAGES SEVERAL TABLES TO MAINTAIN THE ASSOCIATION 
BETWEEN A SYMBOLIC NAME AND ITS HARDWARE NUMBERS 


I dseg.... 
I kst 
T RNT 


J DEFINITION SECTION IN OBJECT SEGMENTS 


[ THERE IS AN INTERPLAY AMONG THE TABLES 


IT dseg AND kst CAN BE CONSIDERED AS A NECESSARY PAIR 
I dseg TELLS THE HARDWARE WHERE SEGMENTS ARE 
[ kst TELLS THE SOFTWARE WHO SEGMENTS ARE 


I THE RNT LISTS ALIASES FOR SEGMENTS LISTED IN THE kst 
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THE LINKER - PHASE I 


mw TEP FAULT 


IT PROLOGUE 


I THE INSTANT A PROGRAM BEGINS TO RUN, IT HAS NOT YET MADE ANY 
CALLS 


I ITS LINKAGE SECTION WILL CONTAIN ONLY UNSNAPPED LINKS BECAUSE 
LINKS ARE NOT SNAPPED UNTIL NEEDED © 


[I AN ATTEMPT TO REFERENCE THROUGH ANY OF THESE LINKS WILL CAUSE 
A HARDWARE FAULT 
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Not To Be Reproduced 


000009 


POINTER TO LINKS' ORIGIN 


F21 


.[ THE FAULT HANDLER 


JT A REFERENCE THROUGH A LINK IS DONE WITH HARDWARE INDIRECTION 


J ALL THE LINK DOES IS TELL THE HARDWARE WHERE TO GO FOR THE 
NEXT REFERENCE 


I USES AN ITS-PAIR 
T T 
L 4 

ti» 


I IF THE HARDWARE FINDS THE BIT PATTERN 100110 AT THE END OF 
THE FIRST WORD OF A LINK, IT FALLS INTO A FAULT TRAP 2. 


I THE WHOLE PROCESSING UNIT IS HALTED AND THE MACHINE IS FORCED 
_TO EXECUTE THE PROGRAM fim {jy \aaeceveT module 


I FROM THIS POINT ON, CONTROL IS IN THE HANDS OF THE 
_, SUPERVISOR 


I THIS IS RING ZERO © 
[ THERE IS NO WAY FOR THE USER TO INTERCEPT THIS FAULT 

I fim ASCERTAINS THAT THE FAULT WAS FAULT TRAP 2 AND CALLS THE 
PROGRAM link_snap_ 


1 link_snap IS THE DYNAMIC LINKER 


IT ‘ink snap FIRST VERIFYS THAT THIS IS A VALID UNSNAPPED LINK 
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- THE. LINKER - PHASE I. 


—eeES 0 ee ee 


sf 46 | 


6-16 


THE LINK 


OFFSET 
LINKAGE 


ADDR2 


IN 
SECTION 


PZ 


3 


THE LINKER - PHASE. = 


SEARCH FOR THE NAME 


link _snap LOOKS AT THE LINK THAT CAUSED THE FAULT AND EXTRACTS 
FROM IT POINTERS BACK TO THE OBJECT SEGMENT 


IN THE OBJECT, AS PART OF THE DEFINITION SECTION, ARE 


" iy E 
OUTWARD-REFERENCING-SYMBOLS" THAT NAME THE SEGMENT AND LOCATION 


WITHIN IT THAT WE WANT 


link_snap OBTAINS THE TWO SYMBOLIC NAMES THAT MAKE UP THE 
VIRTUAL ENTRY DESCRIBING THE FAULTED LINK FROM THIS LIST OF 
SYMBOLS 
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THE LINKER ~ PHASE I 


DEFINITIONS its 


SYMBOLS 


oe ‘ 
MAP | Sa aa aaa 


PAULTED LINK 
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.» ooo CINKER =—.PHASE IT 


® OBTAINING THE SEGMENT NUMBER 


J. A SEGMENT NUMBER DESCRIBES TO HARDWARE THE LOCATION OF A REAL 
SEGMENT; THE DYNAMIC LINKER HAS TO FIND THAT REAL SEGMENT 


IT THE SEARCH RULES 


IT EACH PROCESS HAS A LIST OF PLACES TO SEARCH JUST IN CASE 
LINKAGE FAULTS OCCUR (WHICH IS INEVITABLE) 


I THIS IS THE USER MODIFIABLE ATTRIBUTE OF A PROCESS CALLED 
"THE SEARCH RULES" 


[I A SPECIAL CASE: initiated segments 
"|THE LINKER GOES: To’ THE “RNT® 


I IT - LOOKS UP ‘THE NAME OF:° THE SEGMENT - 


IT OBTAINED DURING ~ 
PHASE I (THE RNT IS A BUNCH OF LINKED LISTS) 


I IF THE NAME IS FOUND, THEN THE NUMBER ASSOCIATED WITH IT 
IS ASSUMED TO BE THE DESIRED SEGMENT NUMBER 


1 IF THE NAME WAS NOT FOUND, THEN WE MOVE ON TO THE NEXT 
SEARCH RULE 
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Not To Be Reproduced 


THE LINKER 


Qn nes 


1Q 


~- PHASE IT! 


—_— ae cee 


6=20 


4901 


S10 


379 


THE LINKER 


oe] 


» 
i 
.¢ 
a 


I THE SECOND RULE IN THE SEARCH RULES IS referencing dir 


] THIS MEANS THE LINKER WILL LOOK IN THE DIRECTORY OF THE 
PROGRAM THAT CAUSED THE LINKAGE FAULT FOR THE SEGMENT 


I ALTHOUGH THIS IS NOTHING MORE THAN THE LIST COMMAND, IT IS 
NOT AN INEXPENSIVE OPERATION 


ei 


ITS PURPOSE IS TO CONTAIN THE GLOBAL NATURE OF THE DYNAMIC 
LINKER IN ITS SEARCH FOR THE SEGMENT 


[. THIS TENDS TO ISOLATE ALL THE PROGRAMS IN A DIRECTORY INTO 
A SUBSYSTEM 


I THE DANGER OF THIS WILL BE STATED LATER 
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THE LINKER =- PHASE ITI 


Ce ce a ee ee) 


; ° 4 
| some dir 


THE REFERENCING DIR 


eam » tate. 


{ &@ prog { prog 
\ 
\ 
bi Seche ice 
THE 
FAULTING 
PROGRAM 
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‘THE LINKER - PHASE II _ 


[ THE LINKER FIGURES THAT THE USER HAS THE PROGRAM AND WILL 
LIST THE CONTENTS OF THE WORKING DIRECTORY 


[ THIS ALSO TENDS TO CONTAIN THE WORKING DIRECTORY INTO A 
SUBSYSTEM OF SORTS 


I IT ALSO LETS THE USER ACCUMULATE A LIBRARY OF INTERWOVEN 
PROGRAMS 
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THE LINKER - PHASE IT 


—__ see 


ety 
end 


another cic 


— i sD 


[wa] 
een ees eee ae: Cones es. 
| er 
aa ~ : , 
ve i 
| / ! 


* 
/ \ : 
c r ! co 
Ce pro j oar {stolen } ‘ 


| 
| 
my = pied |} 
na 3 Sil Nicasl 
“ ms ~~ 


Bow 


Not To Be Reproduced 6-24 


THE -LINKER — PHASE een 


EE | EE. | ee 


J SYSTEM LIBRARIES 
J] HERE BEGINS THE BIG SEARCH 


I AGAIN, A LIST FOR EACH DIRECTORY UNTIL THE LINKER FINDS 
THE SEGMENT IN QUESTION 


I THIS CAN EASILY BECOME THE MOST TIME CONSUMING JOB OF THE 
DYNAMIC LINKER 


I IF THE SEGMENT WAS NOT FOUND IN EITHER THE RNT OR THE 
DIRECTORIES, THEN THE "linkage error" CONDITION IS SIGNALLED 


I IF THE SEGMENT WAS NOT FOUND IN THE RNT, BUT WAS FOUND IN A 
DIRECTORY, ADD IT TO THE kst AND RNT 


see. Di EPLNOE. IN THE kst,, THEN THE PROGRAM. .IS NOT. IN, .THE.ADDRESS 
| SPACE OF THE PROCESS AND’ CAN'T BE USED on oe oe 


[ AFTER ADDING THE PROGRAM INTO THE kst THE LINKER ALSO PLACES 
THE SEGMENT NAME INTO THE RNT 


[ THE SEGMENT NAME WE OBTAINED IN PHASE ONE IS NOW A REFERENCE 
NAME 


ba 


SUBSEQUENT SEARCHES FOR THIS NAME BY FUTURE PROGRAMS IS THIS 
PROCESS WILL FIND A MATCH IN THE RNT, AND HAVE AN INEXPENSIVE 
LINKAGE FAULT 
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THE LINKER - PHASE II 


SS aE eee 


UNUSED 


KSa = 


Not To Be Reproduced 


or 
{ 

nN 

roy 


THE ‘LINKER - PHASE II 


aupeewees ‘Goes eee 


[ LOCATE THE DEFINITION SECTION OF THE JUST FOUND SEGMENT 


It 


OBTAIN THE BIT COUNT FROM THE DIRECTORY 


SUBTRACT 1 


THIS IS THE LOCATION OF THE OBJECT MAP POINTER; USE IT TO 
LOCATE THE OBJECT MAP 


WITHIN THE OBJECT MAP FIND THE ADDRESS OF THE DEFINITION 
SECTION 
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THE LINKER - PHASE II 


(This page intentionally left blank) 
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a 


4 


WALK THROUGH THE DEFINITION SECTION 


T THIS IS ANOTHER LINKED LIST 


I LOOK FOR A CHARACTER ON THE CHAIN THAT MATCHES THE SECOND 
NAME EXTRACTED FROM PHASE ONE. 


T : _ : 3 
1 ASSOCIATED WITH THIS NAME IS A BINARY OFFSET THAT THE 
HARDWARE CAN USE 


[ THE LINKER NOW HAS ALL THE INFORMATION NECESSARY TO SNAP THE 
LINK 


@ SNAPPING THE LINK 
I BACK IN THE FAULTING OBJECT SEGMENT WAS AN UNSNAPPED LINK 


I THE LINKER WILL OVERWRITE THIS INFORMATION WITH THE NEWLY FOUND 
SEGMENT NUMBER AND OFFSET 


I THE LINKER WILL PLACE BINARY 100011 IN THE LAST SIX BITS OF THE 
FIRST WORD OF THE LINK 


I THE LINK IS NOW A STANDARD POINTER =~ IT IS SNAPPED 


IT ANY FURTHER REFERENCES THROUGH THIS LINK WILL NOT RESULT IN A 
FAULT 
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THE LINKER - PHASE II 


1 THIS SNAPPING DOES NOT EFFECT ANY OTHER LINK WITHIN THE LINKAGE 
SECTION 


= 30 FZL 


fo) 
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THE LINKER - PHASE ITI 


UNSNAPPED LINK 


¥ 


SNAPPED LINK 
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THE LINKER =- PHASE II 


® LOADING THE OBJECT SECTIONS | 


I THE NEWLY REFERENCED SEGMENT MAY HAVE A LINKAGE AND STATIC 
SECTION OF ITS OWN THAT MUST BE LOADED INTO MEMORYY 


[ THE DYNAMIC LINKER PERFORMS THE COPYING OF THE STATIC AND 
LINKAGE TEMPLATES INTO THE PROPER AREAS 


J If THE LOT WORD CORRESPONDING TO THE SEGMENT IS EMPTY (I.E. LOT 
(SEGMENT NUMBER) =0) THEN THE LINKER WILL COPY [T 


I GET SOME ROOM IN THE COMBINED LINKAGE AREA FOR THE LINKAGE 
SECTION 


[T COPY THE LINKAGE TEMPLATE FROM THE OBJECT INTO THE SPOT IN 
THE COMBINED LINKAGE AREA 


I PLACE THE ADDRESS OF THE LINKAGE SECTION INTO THE LOT ENTRY 


me 


. . PERFORM THE SAME WITH THE STATIC SECTION, USING THE ISOT AND 
COMBINED STATIC AREA 
I NOTE: THE STATIC MAY BE COMBINED WITH THE LINKAGE 


INFORMATION, IN WHICH CASE THE STATIC WAS LOADED WITH THE 
LINKAGE SECTION | 
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THE LINKER ~- PHASE [I 


OBJECT SEGMENT LINKAGE 
COMBINED LINKAGE AREA OFFSET TABLE 
(LOT) 
TEXT Pec ete al 
i ee 
= — | | ——- | 
LINKAGE ae 
DEFS SECTION ae 
re eee 
LINKAGE 
TEMPLATE 
INTERNAL STATIC 
eReawae: COMBINED STATIC AREA OFFSET TABLE 
STATIC ———— eset) 
cao 7 eS 
: Ee ge me eat al 
INTERNAL 
STATIC 
SECTION 
aaa 


OBJ MAP PTR 
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THE LINKER ~ PHASE II 


® INSTRUCTION RETRY 


[. RETURN TO THE SCENE OF THE CRIME 


I WHEN link snap IS FINISHED, IT RETURNS TO fim 


I fim THEN CAUSES THE INSTRUCTION THAT GENERATED THE LINKAGE 
FAULT TO BE REEXECUTED 


IT WITH THE LINK NOW SNAPPED, A FAULT WILL NOT OCCUR AND THE 
INSTRUCTION WILL FIND THE THING IT WAS LOOKING FOR 


Not To Be Reproduced 6-34 F21 


THE LINKER = PHASE II 


See 0 CREE 0 eR Ee 0 coe 
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BY-PRODUCTS OF DYNAMIC LINKING 


INITIATION 


EVERY SEGMENT THAT A PROCESS WANTS TO USE MUST BE REGISTERED 
WITH BOTH THE dseg AND kst 


desc {,PT0f- SA% 


IF A SEGMENT IS NOT REGISTERED - KNOWN - TO A PROCESS AND IT [IS 
THE OBJECT OF A LINKAGE FAULT, THEN THE DYNAMIC LINKER WILL MAKE 
IT KNOWN 


IT THIS INVOLVES GOING TO THE kst, FINDING OUT THE NEXT FREE 
NUMBER TO USE AND ASSIGNING IT TO THE NEW SEGMENT 


I BECAUSE THIS IS PRETTY MUCH AN UNPREDICTABLE OPERATION AS FAR 
AS AVAILABLE NUMBERS ARE CONCERNED, MULTICS DOES NOT 
GUARANTEE THE CONSISTENCY OF SEGMENT NUMBERS ACROSS PROCESS 
BOUNDARIES 


HIDDEN DANGERS 


4 


THE SEARCH FOR A SEGMENT TO FULFILL THE LINKAGE FAULT CAN CREATE 
DANGERS FOR PROGRAMMERS WHO ARE NOT AWARE OF THE NATURE OF THE 
SEARCH . 


CONSIDER THE FOLLOWING SCENARIO 


I A PROGRAMMER HAS WRITTEN A SET OF PROGRAMS 
THE FIRST PROGRAM IS CALLED driver 
IT CALLS calculate total 


IT THEN CALLS ioa_ TO PRINT THE TOTAL OUT 


LATE (AND ALTHOUGH UNLIKELY, POSSIBLE) driver CALLS A 
PROGRAMMER PROVIDED PROGRAM NAMED formline 
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BY-PRODUCTS OF DYNAMIC LINKING 


IS A SIGNIFICANT CHANCE THAT THE PROGRAMMER SUPPLIED 
ormline_ WILL NOT EXECUTE 


oo] 
th ry 
at 
~ td 
ad 
rm 


I] THE MULTICS SYSTEM SUBROUTINE, loa, ALSO CALLS A PROGRAM 
NAMED formline 


IF ioa_ TOOK A LINKAGE FAULT WHILE CALLING formline_, IT 
WOULD HAVE FOUND THE SYSTEM'S COPY USING THE referencing dir 
RULE, PLACED S NAME IN THE RNT, AND driver WOULD HAVE FOUND 


-TPT TIA? ~~ “a 2 


IT WHEN IT CALLED formline , 


[ NOTE, THEN THAT IT IS POTENTIALLY DANGEROUS TO CALL PROGRAMS 
OUTSIDE THE DIRECTORY OF EXECUTION IF THE NAMES OF SEGMENTS CAN 
BE DUPLICATED ELSEWHERE 


J BINDING ALSO HELPS 


= BINDING 


IT BINDING ITSELF IS A LINKING PROCESS, BUT ITS EFFECTS CAN B& FELT 
SYSTEM WIDE 


I. THIS EXPLANATION WILL CONCERN ITSELF WITH ONLY THE LINKING 
ASPECTS OF BINDING . 


I ONE OF THE ADVANTAGES OF DYNAMIC LINKING IS THAT UNUSED EXTERNAL 
REFERENCES WERE NOT LINKED, SAVING TIME 


I IF A SET OF PROGRAMS MAKE MANY CALLS TO EACH OTHER AND IT IS 
ALMOST UNAVOIDABLE THAT ALL LINKS WILL BE SNAPPED IN THE COURSE 
OF THEIR EXECUTION, THEN PRELINKING WILL BE CHEAPER 
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BY-PRODUCTS OF DYNAMIC LINKING 
[. EACH LINK WILL BE SNAPPED ONCE IN ITS LIFE, AS OPPOSED TO 
MANY TIMES WITH DYNAMIC LINKING 


[ THE PROGRAMMER MUST GIVE UP THE ABILITY TO MAKE CHANGES TO 
OBJECT EASILY; THEREFORE BINDING SHOULD BE DONE ONLY AFTER 
THE PROGRAMS ARE FULLY DEBUGGED 


J. THE BINDER'S TASK 
IT BREAK APART ALL THE SECTIONS OF ALL THE PROGRAMS TO BE BOUND 
[ GROUP ALL LIKE SECTIONS TOGETHER (TEXT WITH TEXT, ETC) 


T COMBINE ALL THE LINKAGE SECTIONS TOGETHER, AND ELIMINATE ALL 
LINK DUPLICATIONS 


J ELEMINATE SOME ENTRYPOINTS INTO THE PROGRAMS, TRIMMING DOWN 
THE DEFINITION SECTION. 


I] GENERATE ONE OBJECT MAP AND OBJECT MAP POINTER 


JT A BOUND SEGMENT MAY ACTUALLY HAVE LINKS LEFT OVER THAT WERE NOT 
RESOLVED AT BINDING TIME; THEY WILL BE HANDLED BY THE DYNAMIC 
LINKER WHEN NEEDED 


Not To Be Reproduced 6-38 F21 


TOPIC: Vit 


The Multics Programming Environment ..... - 
Destruction of the Programming Environment. 
Error Recovery Techniques ... .. . .« « e 

The Multics Programming Environment ..... .- 
Destruction of the Programming Environment. 
Error Recovery Techniques . . . . «6 « «© «© « 


Topic VII MULTICS PROGRAMMING ENVIRONMENT Toric VII 
OBJECTIVES: 
Uron completion of this toric, students should be able to: 


1. Discuss some of the ways in which the Multics process 
environment can be disrupted. 


ac a Arpely Preventive technisaues during Program develoement to 


minimize the number of potentially dangerous Programmins 
errors. 


Multics Vila F214 


VESTRUCTION OF THE PROGRAMMING ENVIRONMENT 


. SOURCE SEGMENT 
IT WHEN INITIATED BY THE COMPILER, NOT GIVEN A REFERENCE NAME 


IT USUALLY NOT MADE KNOWN EXCEPT BY COMPILER 


IT SEGMENT USUALLY NOT KNOWN 


I DESTRUCTION UNLIKELY 


1 OBJECT SEGMENT 


[T SEGMENT READ-EXECUTE ONLY (EXCEPT WHEN DEBUGGER IS SETTING 
BREAKPOINTS) 


T DESTRUCTION UNLIKELY BECAUSE OF HARDWARE PROTECTION 
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DESTRUCTION OF THE PROGRAMMING ENVIRONMENT 


Ce a aT 


® stack n SEGMENT 


I IN [pd] 


. READ-WRITE 


I INCLUDES 
I PROGRAM ACTIVATION HISTORY (STACK) 
{ AUTOMATIC VARIABLES 
I STACK HEADER INFORMATION 


I INCLUDES INITIAL LOT & ISOT ALLOCATIONS 


I DESTRUCTION POSSIBLE THROUGH MISUSE OF AUTOMATIC VARIABLES OR 
BUILT-IN FUNCTIONS 


IT SUBSCRIPTRANGE 
I STRINGRANGE 


I USE OF UNINITIALIZED POINTER TO BASED VARIABLE 
I. SYMPTOMS 


I IF STACK HEADER OVERWRITTEN, FATAL PROCESS ERROR USUALLY 
OCCURS 
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DESTRUCTION OF THE PROGRAMMING ENVIRONMENT 


I STRINGRANGE OFTEN RESULTS IN STORAGE CONDITION (out_of bounds 
ON USER'S STACK) 


1 SUBSCRIPTRANGE CAUSES AUTOMATIC DATA AND/OR PROGRAM 
ACTIVATION INFORMATION TO BE OVERWRITTEN, LEADING TO IMPROPER 
RESULTS AND PROGRAM OPERATION 
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A SS A eS CE 


em ae Re Te 


® [unique] .area.linker SEGMENT 


I IN [pd] 


I READ-WRITE AREA 


JT INCLUDES 


I COMBINED LINKAGE AREA 


I LINKAGE SECTIONS 
I Lor 

I IsotT 

I ‘RNT 


[ COMBINED STATIC AREA 


[. INTERNAL STATIC SECTIONS (VARIABLES) 


to 


USER FREE AREA 

JT EXTERNAL STATIC AND COMMON VARIABLES - PER PROCESS 
EXTERNAL VARIABLE CONTROL INFORMATION 

CONTROLLED VARIABLES 


BASED VARIABLES - NO AREA, IN AN I/O BUFFER 


(en ee OE ce, Se | 


COBOL VARIABLES 


I ASSIGNED LINKAGE AREA 


I BASED STORAGE-ALLOCATED THROUGH hcs Sassign_linkage 
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DESTRUCTION OF THE PROGRAMMING ENVIRONMENT 


ATO || CARSNNEN | NC CNC R: | <emheernnncerupemen SR ESPOSPSSS|||hcrenshe  e epeneN p ND 


s funigquel.area.iinker SEGMENT (continued) 


[T DESTRUCTION POSSIBLE THROUGH 


SUBSCRIPTRANGE 


STRINGRANGE 


USE OF UNINITIALIZED POINTERS 


MISUSE OF AREA 


] -FREETNG SAME BASED-VARIABLS Twice 


JT SYMPTOMS 


4 


IF LINKAGE SECTIONS OVERWRITTEN, IMPROPER PROGRAM OPERATION 


IF LOT OVERWRITTEN, IMPROPER OPERATION OF ALL PROGRAMS 


Ee LSOT OVERWRITTEN, IMPROPER INTERNAL STATIC DATA; 
SUBSEQUENT DESTRUCTION OF OTHER DATA 


IF RNT OVERWRITTEN, UNABLE TO FIND PREVIOUSLY-REFERENCED 
PROGRAMS 


IF VARIABLES (OF ANY STORAGE CLASS) ARE OVERWRITTEN, IMPROPER 
VARIABLE VALUES 


SF EXTERNAL VARIABLE CONTROL INFORMATION OVERWRITTEN, 
IMPROPER COMMUNICATION OF SHARED VARIABLES BETWEEN PROGRAMS; 
IMPROPER DATA VALUES 
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DESTRUCTION OF THE PROGRAMMING ENVIRONMENT 


SS EE ES 


I IF AREA CONTROL INFORMATION OVERWRITTEN, bad_area_format 
CONDITION 
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No 


- 
— 


I 


I : 


DESTRUCTION OF THE PROGRAMMING ENVIRONMENT 


DIRECTORIES, dseg, kst 
NO DIRECT ACCESS TO USER FROM USER RING (RING 4) 


DESTRUCTION UNLIKELY, SEGMENTS PROTECTED BY HARDWARE 


To Be Reproduced bed 


| 


| ed 


No 
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ERROR RECOVERY TECHNIQUES 


ARE CAUSED BY IMPROPER SUBSCRIPTS, BAD SUB 
POINTERS USED IMPROPERLY 


RECOVERY FROM SUBSCRIPTRANGE AND STRINGRANGE © 


I RECOMPILE PROGRAMS CAUSING THESE ERRORS 
FOR THESE CONDITIONS 


I 


PL/1: INSERT A LINE CONTAINING 


STRING OPERANDS, OR 


AND ENABLE CHECKING 


(size, Sstringsize, stringrange, subscriptrange): 


AT THE BEGINNING OF EACH SOURCE SEGMENT, AND RECOMPILE 


WITH -table OPTION 


IT COBOL: USE -runtime_ check AND -table CONTROL ARGUMENTS IN 


cobol COMMAND 
1 FORTRAN: USE -subdscriptrange AND -tabl 
IN fortran COMMAND 


T RUN PROGRAMS 


[ IF CONDITIONS ARE SIGNALLED, USE probe TO 


@e CONTROL ARGUMENTS 


FIND CAUSE 


I FIX PROBLEMS, AND RECOMPILE AS ABOVE UNTIL NO MORE CONDITIONS 


ARE SIGNALLED 


I IF NO MORE CONDITIONS ARE SIGNALLED, BUT PROGRAMMING 


ENVIRONMENT ERRORS STILL PERSIST 


I RECOMPILE WITHOUT THE CONDITION CHECKING, BUT WITH -table 


CONTROL ARGUMENT 


I PROCEED AS GIVEN BELOW UNDER “FURTHER ERROR RECOVERY" 
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R24 


ERROR RECOVERY TECHNIQUES 


I IF ALL ERRORS CORRECTED, RECOMPILE WITHOUT CONDITION CHECKING 


OR 


~table 


@ FURTHER ERROR RECOVERY 


[T bad_area_format CONDITION IN [unique] .area.linker SEGMENT 


1 CAUSED BY OVERWRITING AREA CONTROL INFORMATION 


1 
I 


STORED AT BEGINNING OF AREA 


STORED BETWEEN SPACE ALLOCATIONS 


1 RECOVERY TECHNIQUES (ASSUMES STRINGRANGE AND SUBSCRIPTRANGE 
TESTS HAVE ALREADY BEEN DONE) 


T 


I 


USE area_status COMMAND TO FIND FAULTY LOCATION IN AREA 


USE dump segment COMMAND TO PRINT AREA AROUND THAT 
LOCATION; RECOGNIZABLE DATA MAY LEAD TO THE CAUSE 


USE create area AND set_user storage COMMANDS TO SEPARATE 
USER FREE AREA FROM OTHER GROUPED AREAS 


IF ERROR OCCURS NOW IN USER-SPECIFIED AREA SEGMENT, THEN 
PROBLEM IS IN A USER PROGRAM (NO SYSTEM PROGRAMS EXCEPT 
EXTERNAL VARIABLE MANAGER USE THIS AREA) 


USE probe TO EXAMINE ALL POINTER-QUALIFIED REFERENCES TO 
BE SURE POINTER IS SET PROPERLY 


AFTER SASED-VARIABLES HAVE—-S3EEN-FREED, NULL THEIR POINTER 
TO PREVENT SUBSEQUENT REFEREN RENCE TO FREED SPACE 
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ERROR RECOVERY TECHNIQUES 


J] FATAL PROCESS ERRORS (REPRODUCIBLE) 


[ CAUSED BY OVERWRITING 


I STACK HEADER - 


I LINKAGE OR INTERNAL STATIC SECTIONS OF CRITICAL PROGRAMS 
(10ox_, listen_, command processor _, print_ready_msg _, 
etc.) 


[T RECOVERY TECHNIQUES 


I ATTEMPT TO ISOLATE POINT OF PROCESS FAILURE TO A SINGLE 
PROGRAM STATEMENT 


I USE probe TO 


I SET BREAKS AT KEY POINTS IN THE EXECUTION OF THE 
PROGRAM ; 


J CONTINUE EXECUTION AS EACH BREAK IS REACHED UNTIL FATAL 
ERROR OCCURS 


I] WHEN FATAL ERROR OCCURS, POINT OF FAILURE LIES AFTER 
- LAST BREAKPOINT WHICH WAS REACHED 


T SET BREAKS AFTER THIS POINT TO FURTHER ISOLATE POINT OF 
FAILURE TO A SINGLE STATEMENT 


[T FAILING STATEMENT MAY BE 

I CAUSE OF ERROR 

[T USING INCORRECT DATA AS RESULT OF A PREVIOUS ERROR 
T USE probe TO TRACK ORIGINAL CAUSE OF ERROR 


.[ USE -watch CONTROL ARGUMENT OF trace COMMAND TO ISOLATE 
THE SUBROUTINE WHICH IS DAMAGING A PARTICULAR DATA ITEM 
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BRROR RECOVERY TECHNIQUES 


® FURTHER ERROR RECOVERY (continued) 


I FATAL PROCESS ERRORS (INTERMITTENT) 


{ CAN BE CAUSED BY 
IT UNINITIALIZED DATA VALUES 


IT ANOTHER PROGRAM DESTROYING YOUR PROGRAM'S DATA 


[T RECOVERY TECHNIQUES 
IT IN A NEW PROCESS, RUN JUST THE FAILING PROGRAM 


I IF PROGRAM OPERATES CORRECTLY, ANOTHER PROGRAM MAY BE 
SOURCE OF ERROR 


T IF PROGRAM FAILS (ESPECIALLY FAILS INTERMITTENTLY OR IN 
DIFFERENT WAYS), USE probe TO LOOK FOR UNINITIALIZED 


VARIABLES 
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TOPIC VIII 


Other Useful Debugging Tools. 
list external variables . 
iise external variables . 
reset_external variables. 
reset_ external variables. 
delete external variables 
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Toric VIII 


OBJECTIVES: 


OTHER DEBUGGING COMMANDS 


Toric VIII 


Upon completion of this topic, students should be able to: 


1. Manipulate external variables with the followins commands: 


2. Find and 
followins 


listuwexternal_variables (lev) 


resetlexternal_variables (rev) 


delete_external_variables (dey) 


correct erroblems related to Ilinkinga 


commands: 


Printubindomare (€rbm) 


Printulink info (pli} 


resolve _linkase_error (rlea) 


with the 


3. Use the trace_stack (ts) command in conJunction with trace 
and probe to determine the state of the process when an error 


oOccuUPSs. 


Multics 


Vii 


eA 


list external variables 


The list_external_ variables command prints information about 
variables managed by the system for the user, including FCRTRAN common 
and PL/I external static variables whose names do not contain dollar 
signs. The default information is the location and size of each 
specified variable. 


Usage 


List_external variables names {-control args} 


where: 
i names 
are names of external variables, separated by spaces. 
2.  control_args 
can be chosen from the following: 
-unlabeled common, -uc 
is the name for unlabeled {or blank) commen. 
-long, -lg 
prints how and when the variables were allocated. 
prints information for each variable the system is 
managing. 
~no_ header, -nhe 
Suppresses the header. 
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reset external variables 


Name: reset external variables 


The reset external variables command reinitializes system-managed 


variables to the values they had when they were allocated. 


Usage 


reset_external variables names {-control arg} 


where: 

cor names 
are the names of the external variables, 
Spaces, to be reinitialized. 

2% control arg 


is -unlabeled_ common (or -uc) to indicate unlabeled 


block) common. 


Note 


separated by 


(or 


A variable cannot be reset if the segment containing 


the initialization information is terminated 


variable is allocated. 
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delete external variables 


The delete external variables command deletes from the user's 
name space specified variables managed by the system for the user. 
All links to those variables are unsnapped and their storage is freed. 


Usage 


delete external variables names {-control arg} 


where: 

he names 
are the names of the external variables, separated by 
spaces, to be deleted. 

2. control arg 


is ~unlabeled_ common (or -uc) to indicate unlabeled (or 
blank) common. 
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Name: 


print bind map 


print_bind map 


The print_bind_ map command displays all or part of the bind map 


of an object segment generated by version number 4 or subsequent 


versi 


Usage 


where 


1] 


ee @ 


2. 


3% 
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ons of the binder. 


print_bind_map path {components} {-control args} 


. 
° 


path 
is the pathname of a bound object segment. 


components 

are the optional names of one or more components of this 
bound object and/or the bindfile name. Only the lines 
corresponding to these components are displayed. A 
component name must contain one or more nonnumeric 
Characters. If it is purely numerical, it is assumed to 
be an octal offset within the bound segment and the lines 
corresponding to the component residing at that offset are 
displayed. A numerical component name can be specified by 
preceding it with the -name control argument (see Delow). 
I= no component names are specified, the entire bind map 
is displayed. 


control args 
may be chosen from the following list: 


-long, -lg 
prints the components' relocation values (also printed in 
the default brief mode), compilation times, and source 
languages. 


—~name STR, -nm STR 
is used to indicate that STR is really a component name, 
even though it appears to be an octal offset. 


~no_ header, -nhe . 
omits all headers, printing only lines concerning the 
components themselves. 


if 


E22 


Name: 


print link info, pli 


print_link_info, pli 


The print link _info command prints selected items of information 


for the specified object segments. 


Usage 


print_link_info paths {-control args} 


where: 
dig paths 

are the pathnames of object segments. 
2. control_args 


Note 


apply 


can be chosen from the following list. (See "Note" 
below.) 
~length, <-lin 


‘print only the lengths of the sections in pathi. 


=entry, -et ; 
Print only a listing o 
Giving their symbolic n 
within the segment. 


f the pathi external 
ar nd their relat 


efinitions, 
lames ar e 


addresses 


~link, -lk 
print only an alphabetically sorted listing of all the 
external symbols referenced by pathi. 


-long 
prints more information when the header is printed. 
Additional information includes a listing of source 
programs used to generate the object segment, the contents 
of the "comment" field of the symbol header (often 
containing compiler options), and any unusual values in 
the symbol header. 


-header, -he 
prints the header (The header is not printed by default, 


if the -length, -entry, or -link control argument is 
specified.) 


~no_header 
Suppresses printing of the header. 


Control arguments can appear anywhere on the command line and 
to all pathnames. 
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print link info, pli 


Example 


{ print _link_info program -long -length 


program 07/30/76 1554.2 edt Fri 


Object Segment >udd>Work>Wilson>program 
Created on 07/30/76 0010.1 edt Fri 
by Wilson.Work.a 


using Experimental PL/I Compiler of Thursday, July 26, 1976 at 21:38 


Translator: PL/I 
Comment: map table optimize 
Source: 
07/30/76 0010.1 edt Fri >user_ dir dir>work>Wilson>s>s>program.pl 
12/15/75 1338.1 edt Mon >library dir _dir>include>linkdcl.incel. Pai 
06/30/75 1657.7 edt Mon >library_ dir di ir>include>object info incl. pil 
LO/06/7 2 2206.8 edt Fri >library.- dir_ dir>include>source | _map.incl.pl 
OS/iS7r2- 15.2.4 ede Thu >library_ air. _dir>include>symbol_ block.in¢1. ae 
01/17/73 1551.4 edt Wed >library_ dir dir>include>pll _symbol_ Slock.wtnclepll 
Attributes: relocatable,procedure,standard 
Object Text Defs Link Symb Static 
Start 0 0 3450 3620 3656 3630 
Length Tiilio 3450 150 36 o215 0 
<ready> — 


Also printed is: 


Severity, 1f it is nonzero. 
Entrybound, if it is nonzero. 
Text Boundary, if it is not 2. 
Static Boundary, if it is not 2. 
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Name : 


The 


linkage 
locates 
linkage 
issued 

located 


reslve linkage error, rle 


resolve linkage error, rle 


resolve linkage error command is invoked to satisfy the 
fault after a process encounters a linkage error. The program 
the virtual entry specified as an argument and patches the 
information of the process so that when the start command is 
the process continues as if the original linkage fault had 
the specified virtual entry. 


resolve linkage error virtual_entry 


where vi 


Notes 


For 


cv_entry_ 


Examples 


rtual_entry is a virtual entry specifier. 


an explanation of virtual entries, see the description of the 
subroutine. 


myprog 

Error: Linkage error by >udd>m>vv>myprog|123 
referencing subroutineSentry 

Segment not found. 

r 1234 2.834 123.673 980 level 2, 26 


rle mysubSmysub_ entry 
r 1234 0.802 23.441 75 level 2, 26 


start 
«ee. Myprog is running 
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trace stack, ts 


Name: trace stack, ts 


The trace stack command prints a detailed explanation of the 
Current process stack history in reverse order (most recent frame 
first). For each stack frame, ail available information about the 
procedure that established the frame (including, if possible, the 
Source statement last executed), the arguments to that (the owning) 
procedure, and the condition handlers established in the frame are 
printed. For a description of stack frames, see "“"Multics Stack 
Segments" in Section!IV of the MPM Subsystem Writers' Guide. 


The trace stack command is most useful after a fault or other 
error condition. If the command is invoked after such an error, the 
machine registers at the time of the fault are also printed, as well 
as an explanation of the fault. The source line in which it occurred 
Can be given if the object segment is compiled with the -table option. 


Usage 


trace stack {-control args} 


where control args can be selected from the following: 


“-brief, -bf 
Suppresses listing of arguments and handlers. This 
control argument cannot be specified if -long is also 
specified as a control argument. 


-long, -lg 
Prints octal dump of each stack frame. 


~depth N, -dh N 
dumps only N frames. 


Output Format 


When trace stack is invoked, it first searches 
backward through the stack for a stack frame containing 
saved machine conditions as the result of a signalled 
econda tion. If such a frame is found, tracing proceeds 
backward from that point; otherwise, a comment is printed 
and tracing begins with the Stack frame preceding 
trace stack. 


ond 


If a machine-conditions frame is found, tra 

repeats the system error message describing the fault. 
Unless the -brief control argument is specified, 
trace stack also prints the source line and fauiting 
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trace stack, ts 


instruction and a listing of the machine registers at the 
time the error occurred. 


The command then performs a backward trace of the 
Stack, for N frames if the -depth N argument was 
specified, or else until the beginning of the stack is 
reached. 


Por each stack frame, trace stack prints the offset 
of the frame, the condition name if an error occurred in 
the frame, and the identification of the procedure that 
established the frame. I£ the procedure is a component of 
a bound segment, the bound segment name and the offset of 
the procedure within the bound segment are also printed. 


The trace stack command then attempts to locate and 
print the source line associated with the last instruction 
executed in the procedure that owns the frame (that is, 
either a call forward or a line that encountered an 
error). The source line can be printed only if the 
procedure has a symbol table (that is, if it was compiled 
with the -table option) and if the source for the 
procedure is available in the user's working directory. 
TE the source line cannot be printed, trace stack prints a 
comment explaining why. = 


Next, trace stack prints the machine instruction last 
executed by the procedure that owns the current frame. [If 
the machine instruction is acall to a PL/I operator, 
trace stack also prints the name of the operator. If the 
instruction is a procedure call, trace stack suppresses 
the octal printout of the machine instruction and prints 
the name of the procedure being called. 


Unless the -brief control argument is specified, 
trace stack lists the arguments supplied to the procedure 
that owns the current frame and also lists any enabled 
condition, default, and clean-up handlers established in 
the frame. 


Lf the -~long control argument is specified, 
trace stack then prints an octal dump of the stack frame, 
with eight words per line. 
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trace stack, ts 


Example 
After a fault that reenters the user environment and 


reaches command level, the user invokes the trace stack 
command. 


For example, after quitting out of the list command, 
the following process history might appear: 
! list 
Segments=8, Records=3 
rew OQ mailbox 
row 
QUIT 


! trace stack 
quit in ipc_ Sblock|156 


(>system library 1>bound_ command _loop_|[156) 
No symbol table for ipc_ 
256 400010116100 emp pr4jlo 


Machine vegisters at time of fault 

pro (ap) 26314656 pll operators Soperator_ table|162 
(external symbol in separate nonstandard 
text section) 


prl (ab) 1031264 scs|264 

pr2 (bp) 14112200 as_linkage|12200 

pr3 (bb) 11310 tc _datalo 

pr4 (lp) 25312250 !BBBUGJFKPBWCNZ.area.linker| 2250 
(internal static|0 for ipe_) 

prs (1b) 2441/3614 stack 4]361 

pr6é (sp) 2441/3500 stack 413500 ( -> “kcpMbLH +0000000") 

pr7 (sb) 2441/0 stack _4]0 

x0 73 rl 0 X2 0 x3 600000 

x4 0 x5 32 x6 3033 x7 4 


a 000000000000 q 000000000004 e090 


Timer reg - 1746005, Ring alarm reg - 0 


SCU Data: 


4030 400270250011 000000000021 400270000000 000000672000 
000156000200 000154000700 002250370000 600044370120 


Connect Fault 
At: 2701156. i 
On: cpu a (#0 
Indicators: Dar 


) 
1156 (bound command loop |156) 
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trace stack, rs 


APU Status: xSsf, sd-on, pt-on, fabs 

CU Status: rll; Les); ELE 

Instructions: 
4036 002250 3700 00 epp4 2250 
4037 6 00044 3701 20 epp4 pr6144,* 


Time stored: 08/02/77 1635.5 edt Tue (104541674361226602) 
Ring: 4 


Backward trace of stack from 244|/3500 


3500 quit ipe Sblock|156 (bound_command_loop |156) 
No symbol table for ipc_ 
156 400010116100 cmpq pr4|10 
ARG 1: 25315704 !BBBUJGJ]FKPBWCNZ.area.linker|5704 
ARG 2: 244/3152 stack 413152 
ARG 3: 0 


2720 tty _ Stty get_line|2442 (bound_iox_/11546) 
No symbol table for tty_ 
call_ext_out to ipe $block 
ARG 1: 2531/4320 !BBBJGJ FKPBWCNZ.area.Llinker| 4320 
(internal static|]154 for find_iocb) 


ARG 2: 244|/2660 stack 4/2669 ( -> "fo stuff”) 
ARG 3: 128 
ARG 4: 0 
ARG 5: 0 
2400 Listen S$listen_1461 (bound_command_ loop |1325) 


No symbol table for listen_ 
call_ext_out to iox $get_ line 
ARG 1: ™* 
on "cleanup" call listen_|1256 (bound_command_loop_|1122) 


2100 process overseer Sprocess overseer |473 (bound _command_loop |214 
No symbol table for process overseer. 
call_ext_out_dese to listen $listen_ 
Argument list header invalid. 
on “any other" 
call standard _default_handler $standard_default_ handler 3 
(external symbol in separate nonstandard text section) 


2000 user _init admin _Suser_init_admin_|36 (bound_command_loop [|21676) 
No symbol table for user_init_admin 
21676 700036670120 tsp4 Dr7136,* alm_call 


No arguments. 
End of trace. 
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trace stack, ts 


r 1635 1.756 40.790 207 level 2, 9 
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Name: area status 


The area status command is used to display certain information 
about an area. 


Usage 


¢ 


area status area name {-control args} 


where: 
1. area_name 
is a pathname specifying the segment containing the area 
to be looked at. 
23 control args 
can be chosen from the following: 
~trace 
displays a trace of all free and used blocks in the area. 
-offset N, -ofs N 
specifies that the area begins at offset N (octal) in the 
given segment. 
-long, -lg 
dumps the contents of each block in both octal and ASCII 
format. 
Note 


If the area has internal format errors, these are reported. The 
command does not report anything about (old} buddy system areas except 
that the area is in an obsolete format. 
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Name: cancel_cobol program, ccp 


The cancel _cobol program command causes one or more programs in 
the current COBOL run unit to be cancelled. Cancelling ensures that 
the next time the program is invoked within the run unit, its data is 
in its initial state. Any files that have been opened by the program 
and are still open are closed and the COBOL data segment is truncated. 
Refer to the run_cobol command for information concerning the run unit 
and the COBOL runtime environment. 


Usage 


cancel _cobol_ program names {-control arg} 


where: 

is names 
are the reference names of COBOL programs that are active 
in the current run unit. If the name specified in the 
PROG-ID statement of the program is different from its 
associated nmamei argument, namei must be in the form 
refnameSPROG-ID. 

Zi control arg 
may be ~retain_data or -retd to leave the data segment 
wesceusued with the program intact for debugging purposes. 
(See "Notes" below.) 

Notes 


The pee eke of the cancel _cobol_ program command and the execution 
of the CANCEL statement from within ~a COBOL Program are similar. The 
only - ee is that if anamei argument is not actually a 
component of the current run unit, an error message is issued and no 
action is taken; for the CANCEL statement, no warning is given in such 
a case. 


To preserve program data for debugging purposes, the -retain data 
control argument should be used. The data associated with the 
cancelled program is in its last used state; it is not restored to its 
initial state until the next time the program is invoked in the run 
unit; 


Refer to the following related commands: 
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cancel cobol program, ccp 


display cobol run unit, dcr 
stop _cobol_run, scr 
run cobol, re 
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Name: create area 


soe sei gms GS day gee Al 


= ate area command creates an area and initializes it with 
user-specified area management control information. 
Usage 


Create area virtual ptr {-control_ args} 


where: 


1. virtual ptr 
Ts a virtual pointer to the area to be created. The 
Syntax of virtual pointers is described in the cv_ptr_ 
Subroutine description. If the segment already exists, 
the specified portion is still initialized as an area. 


Ze control args 
Can be chosen from the following: 


“no freeing 
allows the area management mechanism to use a faster 
allocation strategy that never frees. 


-dont free 


—~ 
1s used du 


mg debugging to disable the free mechanism. 
This does n a 


fFfect the allocation strategy. 


oO rs 


-zero on alloc 


Instructs the area management mechanism to clear blocks at 
allocation time. 


-zero on free 
instructs the area management mechanism to clear blocks at 
free time. 


~extend 
causes the area to be extensible, i.e., Span more than one 
Segment. This feature should be used only for perprocess, 
temporary areas. 


-~size N 
specifies the octal size, in words, of the area being 
created or of the first component, if extensible. If this 
control argument is omitted, the default size of the area 
is the maximum size allowable for a segment. 


-id STR 


specifies a string to be used in constructing the names of 
the components of extensible areas. 
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Create data segment, cds 


Name: create data segment, cds 


The create data segment command translates a create data segment 
Source program (CDS program) into an object segment. A listing 
segment is optionally created. These results are placed in the user's 
working directory. This command cannot be called recursively. 


The source for create data segment programs is standard PL/I with 
the restriction that "the program include a call to the 
Create data segment subroutine. The create data segment subroutine 
creates a standard object segment from PL/I data Structurés passed to 
it aS parameters. These data structures can be initialized with 
arbitrarily complex PL/I statements in the CDS program. (See the MPM 
Subroutines for a description of the create data_segment_ subroutine.) 


Usage 


Create data segment path {-control_arg} 


where: 
Le path 
; is the pathname of a CDS segment that is to be translated 

into an object segment. T£ path does not have a cds 
suffix, one is asssumed. However, the cds suffix must be 
the last component of the name of the source segment. 

2 control arg 
can be -list (-ls) to produce a source listing of the CDS 
program used to generate the data segment followed by 
object segment information (as printed by the 
print link info command described in the MPM Subsystem 
Writers' Guide) about the actual object segment created. 

Note 


Since the create data segment command invokes the PL/I compiler 
to first compile the CDS s@égment, any errors that the comviler finds 
are reported by its standard technique. If any errors with a severity 
greater than 2 occur, the CDS run is aborted and an object segment is 
not created. 
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Name: cumulative page trace, cpt 

The cumulative page trace command accumulates page trace 
that the total set of pages used during the invocation of a command or 
subsystem can be determined. The command accumulates data from one 
invocation of itself to the next. Output from the command is in 
tabular format showing all pages that have been referenced by the 
user's process. A trace in the format of that produced by the 
page trace command can also be obtained. 


The cumulative page trace command operates by sampling and 
reading the system trace array after invocation of a command and at 
repeated intervals. Control arguments are given to specify the 
detailed operation of the cumulative page trace command. 


The command line used to invoke the cumulative page trace command 
includes the command or subsystem to be traced as well as optional 
control arguments. 


Usage 


Cumulative page trace command line {-control args} 


where: 
ae command line 
Is acharacter string to be interpreted by the command 
processor as a command line. If this character string 
contains blanks, it must be surrounded by quotes. All 
procedures invoked as a result of processing this command 
line are metered by the cumulative page trace command. 
par control args 
may be chosen from the following: 
-count, -ct 
prints the accumulated results, giving the number of each 
page and the number of faults for each page. 
-flush 


clears primary memory before each invocation of the 
command line and after each interrupt. This helps the 
user determine the number of page faults but increases the 
cost. 


-interrupt N -int N 
interrupts execution every N virtual CPU milliseconds for 
page fault sampling. 


J 
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ry 
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cumulative page trace,cpt 


-long, -lg 
produces output in long format, giving full pathnames. 


-loop N 
calls the command to be metered N times. 


-print, -pr 
prints the accumulated results, giving the number of each 
page referenced. 


-~print_linkage faults 
prints all accumulated linkage faults and calls to the 
hes Smake_ptr entry point. 


“reset, =-rs 
resets the table of accumulated data. If the table is not 
reset, data from the current use of cumulative page trace 
is added to that obtained earlier in the process. 


~short, -sh 
formats output for a line length of 80. 


-~sleep N 
waits for N seconds after each call to the command being 
metered. 


-timers 
includes all faults between signal and restart. 


-total, -tt 
prints the total number of page faults, the total number 
of segment faults, and the number of pages referenced for 
each segment. 


-trace jinkage faults 
accumulates linkage faults information along with page and 
segment fault information. 


-trace path 
writes the trace on the segment named path using an I/90 
switch named cpt.out; cumulative page trace attaches and 
detaches this switch. 


Notes 


At least one of three generic operations must be requested. They 
may all be combined and, if so, are performed in the following order: 
resetting the table of accumulated data, calling the command to be 
metered, applying the specified control arguments, and printing the 
results in the specified format. 
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The default mode of operation permits no interrupts for page 
fault sampling. If the command or subsystem to be metered will take 
more than several hundred page faults, linkage faults, or other system 
events that are indicated in the page trace array, it is recommended 
that interrupts be requested. If the user does not know a suitable 
value for the -interrupt control argument, the value recommended is 
400 milliseconds. If this figure is too large, messages indicate that 
some page faults may have been missed; a smaller value can then be 
chosen. The cost of a smaller value is high and may cause additional 
side effects. If the command or subsystem to be metered includes the 
taking of CPUT interrupts, then the -timers control argument should be 
given. This control argument causes some of the page faults of the 
metering mechanism to be included as well. 


Only one of the control arguments -print, ~-count, or -total may 
be given. Each of these control arguments produces printed output in 
a different format. If more than one format is desired, the command 
must be invoked once for each format. 

Examples 

The command line: 

cpt "pli test" -interrupt 400 -trace trace out 
calls the pll command to compile the program named test, requesting an 
interrupt every 400 milliseconds to obtain page trace information. 
Trace information is placed in a segment named trace out. 

The command line: 

cpt “list -pn >udd>Multics™ -loop 2 -sleep 10 


calls the list command twice, and sleeps for 10 seconds between calls. 


The command line: 
Cpt -print 


prints the accumulated results of previous metering. 


ev ptr 


Name: cv otr 


The cv_ptr_ subroutine converts a virtual pointer to a pointer 
value. A virtual pointer is a character string representation of a 
pointer value. The types of virtual pointers accepted are described 
under "Virtual Pointers" below. 

Usage 


declare ev.ptr. entry (char (*), fixedibin(35)) returns! (ptr); 


ptr_value = cv_ptr_ (vptr, code); 


where: 

Le vptr is the virtual pointer to be converted. (Input) 
See "Virtual Pointers" below for more information. 

Ds code is a standard status code. (Output) 

cer ptr_value is the pointer that results from the conversion. 


(Output) 


Entry: cv_ptr_S$terminat 


a 


This entry peint is called to terminate the segment that has been 
initiated by a previous call to cv_ptr_. 
Usage 

declare cv_ptr Sterminate (ptr); 


call cv_ptr_Sterminate (ptr_value); 


where ptr value is the pointer returned by the previous call to 
cv_ptr_. (Input) 
Notes 

Pointers returned by the cv ptr Subroutine cannot be used 4s 


entry pointers in calls to cu $gen call or cu $make entry value. The 
cv_ptr_ subroutine constructs the returned pointer to a Segment in a 
way that avoids copying of the segment's linkage and internal static 
data into the combined linkage area. The cv entry subroutine is used 
to convert virtual entries to an entry value. 7 


Not To 38e Reproduced A-9 | F21 


cv ptr 


The segment pointed to by the returned ptr_value is initiated 
with a null reference name. The cv_ptr_Sterminate entry point should 


be Called to terminate this null reference name. 


Virtual Pointers 


The cv ptr subroutine converts virtual pointers that contain one 
or two components -- a segment identifier and an optional offset into 
the segment. Altogether, fourteen forms are accepted. They are shown 
in the table below. 


In the table that follows, W is an octal word offset from the 
beginning of the segment. It may have avalue from 0 to 777777 


inclusive. B is a decimal bit offset within the word. It may have a 
value from 0 to 35 inclusive. 


Mo 
! 
ts 
(/) 
Urs | 
ND 
f- 
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Virtual 
Pointer 


path|W(8) 


ref nameSentry pt 
ref namesw(B) 


ref namesSw 
ref names 


segno|W(B) 


segno|WwW 
segno| 
segno 


segnolentry pt 


= os 
whose octal 


Interpretation 


points to octal word W, decimal bit B of segment 
identified by absolute or relative pathname path. 


Same as path|W({0). 
same as path|0(0). 
same as path!0(0). 


points to word identified by entry point entry pt 
in segment identified by path. 


points to word identified by entry point entry pt 
in segment whose reference name is ref name. 


points to octal word W, decimal bit B of segment 
whose reference name is ref name. 


same as ref nameSw(0). 
Same as ref nameS0O(0). 


word W, decimal bit B of segment 
egment number is segno. 


points to octal 
s 


Same as segno!|W(0). 
Same as segno|0(0). 
same as segno|0(0). 


points to word identified by entry point entry pt 
in segment whose octal segment number is segno. 


A null pointer is represented by the virtual pointer 77777/1, by -lll, 


or by -l. 
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Name: delete external variables 
The delete external variables command deletes from the user's 


name space specified variables managed by the system for the user. 
All links to those variables are unsnanped and their storage is freed. 


Usage 


delete external variables names {-control_arg} 


where: 

bs names 
are the names of the external variables, separated by 
Spaces, to be deleted, 

26 control arg 


is -unlabeled_ common (or -uc) to indicate unlabeled (or 
blank) common. 
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The display cobol run_unit command displays the current state of 
a COBOL run unit. The minimal information displayed tells which 
programs compose the run unit. Optionally, more detailed information 
can be displayed concerning active files, data location, and other 
aspects of the run unit. Refer to the run cobol command for 
information concerning the run unit and the COBOL runtime environment. 


Usage 


display cobol_run_unit {-control_args} 


where control args may be chosen from the following list: 


~long, -lg 
causes more detailed information about each COBOL program 
in the run unit to be displayed. 


~files 
displays information about the current state of the files 
that have been referenced during the execution of the 
current run unit. 

“all, -a 


ints information about all programs in the run unit, 
including those that have been cancelled. 


Refer.to the following related commands: 


rin -cobol, 2¢ 
stop cobol run, scr 
cancel cobol program, ccp 
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Name: display pllio_err, dpe 


The display pllio error command is designed to be invoked after 
the occurrence of an I/O error signal during a PL/I I/O operation. It 
describes the most recent file on which a PL/I I/O error was raised 
and displays diagnostic information associated with that type of 
error. 


Example 
The command line: 
display pllio_error 
might respond with the following display: 
Error on file afile 
aitle: viile. atile 
Attributes: open input keyed record sequential 
Last i/o operation attempted: write from 


Attempted "write" operation conflicts with file “input” attribute. 
Attempted "from" operation conflicts with file "input" attribute. 
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Name: dump segment, ds 


The dump_segment command prints, in octal or hexadecimal format, 
selected portions of a segment. It prints out either four or eight 
words per iine and can optionally be instructed to print out an edited 
version of the ASCII, BCD, EBCDIC (in 8 or 9 bits), or 4=-bit byte 
representation. 


Usage 


dump segment path {first} {n_words} {-control args} 


where: 

Ls path 
is the pathname or (octal) segment number of the segment 
to be dumped. If path is a pathname, but looks like a 
number, the preceding argument should be the -name (or 
—-mm) control argument (see below). 

26 first 
is the (octal) offset of the first word to be dumped. IE£ 
both first and n_words are omitted, the entire segment is 
dumped. 

Be n words 
is the (octal) number of words to be dumped. ff first is 
supplied and n words is omitted, 1 is assumed. 

4, control ards 
can be chosen from the following: 

—4bit 

prints out a translation of the octal or hexadecimal dump 
based on the Multics unstructured 4-bit byte. The 


ranslation ignores the first bit of each 9-bit byte and 
uses each of the two groups of four bits remaining to 
generate a digit or a sign. 


~address, -add 
prints the address (relative to the base of the segment) 
with the data. This is the default. 


-bed 


prints the BCD representation of the words in addition to 
the octal or hexadecimal dump. There are no nonprintable 
BCD characters, so periods can be taken literally. 


~block N, -bK N 
Gumps words in blocks of N words separated by a blank 
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dump segment, ds 


line. The offset, if being printed, is reset to initial 
value at the beginning of each block. 


-character, -ch, ~ascii 
prints the ASCII representation of the words in addition 
to the octal or hexadecimal dump. Characters that cannot 
be printed are represented as periods. 


~ebcdic9 
prints the EBCDIC representation of each 9-bit byte in 


addition to the octal or hexadecimal dump. Characters 
that cannot be printed are represented by periods. 


-ebcdics 
prints the EBCDIC representation of each eight bits in 
addition to the octal or hexadecimal dump. Characters 
that cannot be printed are represented by periods. If an 
odd number of words is requested to dump, the last four 
bits of the last word do not appear in the translation. 


-header, —-he 
prints a header line containing the pathname ‘or segment 
mumber) of the segment being dumped as well as the 
date-time printed. The default is to print a header only 
if the entire segment is being dumped, i.e., neither the 
first nor the n_words arguments is specified. 


~hex8 
prints the dumped words in hexadecimal with nine 
hexadecimal digits per word rather than octal. with 12 
octal digits per word. 

~hex9 
prints the dumped words in nexadecimai with eight 
hexadecimal digits per word rather than 12 octal digits 
per word. Each pair of hexadecimal digits corresponds to 
the low-order eight bits of each 9-bit byte. 

-long, -lg 


prints eight words on a line. Four is the default. This 
control argument cannot be used with -character, -bdcd, 
-4bit, -ebcdic8, -ebcdic9, or ~short. (Its use with these 
control arguments, other than -short, results in a line 
longer than 132 characters.) 


-name, —-nm 
indicates that the following argument is a pathname even 
though it may look like an octal segment number. 


“no_address, ~-nad 
does not print the address. 
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-no_header, -nhe 
suppresses printing of the header line even though the 
entire segment is being dumped. 


-no_ offset, -nofs 
does not print the offset. This is the default. 


-offset N, -ofs N 
prints the offset (relative to N words before the start of 
data being dumped) along with the data. LEON. “is net 
given, 0 is assumed. 


~short, -sh 
compacts lines to fit on a terminal with a short line 
length. Single spaces are placed between fields, and only 
the two low-order digits of the address are printed, 
except when the high-order digits change.: This shortens 
output lines to less than 30 characters. 


Note 


Only - one of the control arguments: -ebcdics8, 
-ebcdic9, -character, -bed, or ~-4bit can be specified. 
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Name: io call, io 


The io call command performs an operation on a designated I/0 
switch. ~ 


Usage 


io_call opname switchname {args} 


where: 
i opname 
designates the operation to be performed. 
2 Switchname 
is the name of the I/O switch. 
oy args 


may be one or more arguments, depending on the particular 
operation to be performed. 


The opnmames permitted, followed by their alternate forms where 
applicable, are: 


attach Look iocb 

close | open | 

control | position 

delete record, delete print locb 

detach iocb, detach put_chars 

destroy iocb read_key 

find_iocb : read length 
get_chars read record, read 
get line rewrite record, rewrite 
modes seek key 
move_attach write record, write 


Usage is explained below under a separate heading for each 
designated operation. The explanations are arranged functionally 
rather than alphabetically. 


Unless otherwise specified, if a control block for the I/0 switch 
does not already exist, an error message is printed on error output 
and the operation is not performed. If the requested operation is not 
Supported for the switch's attachment and/or opening, an error message 
is printed on error output. 
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The explanations of the operations cover only the main points of 
interest and, in general, treat only the cases where the I/O switch is 
attacned to a file or device. For full details see the descriptions 
of the iox subroutine and the I/0 modules in the MPM Subroutines and 
Section V, "Input and Output Facilities," in the MPM Reference Guide. 


Operation: attach 


io_call attach switchname modulename {args} 


where: 


de modulename 
is the name of the I/0 module to be used in the 
attachment. If modulename contains less-than (<) or 
greater-than (>) characters, it is assumed to be a 
pathname, otherwise, it is a reference name. 


a args 
may be one or more arguments, depending on what is 
permitted by the particular I/O module. 


This command attaches the I/O switch using the designated I/0 
module, The attach description is the concatenation of modulename and 
args separated by blanks. The attach description must conform to the 


requirements of the I/O module. I£ the I/0 modulename is specified by 


a pathname, it is initiated with a reference name equal to the 
entryname. Ti the entryname or reference name does not contain a 
dollar sign ($), the attachment will be made by calling 
modulenameSmodulenameattach. If a dollar sign is specified, the entry 
point specified is called. See "Entry Point Names" in the MPM 


Reference Guide. 


T£ a control block for the I/0 switch does not already exist, one 
is created. 


Operation: detach iocb, detach 


io_call detach switchname 


This command detaches the I/0 switch. 
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Operation: open 


io_call open switchname mode 


where mode is one of the follewing opening modes, which may be 
specified by its full name, or by an abbreviation: 


stream_input, si keyed sequential input, ksqi 
stream _ | output, so keyed _ sequential output, ksqo 
stream, input_output, sio keyed _ sequential update, ksqu 
sequential input, sgi divecft_input, di 

sequential output, sqo direct. output, do 

sequential input_output, sqio direct update, du 


sequential” update, squ 


This command opens the I/0 switch with the specified opening 
mode, 


Operation: close 


io_call close switchname 
This command closes the I/O switch. 


Operation: get_line 


io_ call get_line switchname {N} {-control_args} 


where: 

ae N 
is a decimal number greater than zero specifying the 
maximum number of characters to be read. 

2% control _ args 


Can be selected from the following: 


-segment path {offset}, -sm path {offset} 
specifies that the line read from the I/O switch is to be 
stored in the segment specified by path, at the location 
specified by offset. 


-nnl 


specifies that the newline character, if present, is 
deleted from: the end of the line. 
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-nl 
specifies that a newline character is added to the end of 
the line if one is not present. 

-lines 


specifies that the offset, if given, is measured in lines 
rather than characters. This control argument only has 
meaning if the ~segment control argument is also 
specified. 


This command reads the next line from the file or device to which 
the I/O switch is attached. If Nis given, and the line is longer 
than N, then only the first N characters are read. 


If the -segment control argument is not specified, the line read 
is written onto the I/O switch user output, with a newline character 
appended if one is not present and -nnl has not been specified. 


Tf the -segment control argument is specified, the line is 
in the segment specified by path. If this segment does not exi 
is created, If offset is specified, the line is stored at that 
position relative to the start of the segment. This is normally 
measured in characters, unless -lines has been used. If offset is 
omitted, the line is appended to the end of the segment. The bit 
count of the segment is always updated to a point beyond the newly 
added data. 


Operation: get chars 


io_call get chars switchname N {-control args} 


where: 


alg N 
is a decimal number greater than zero svecifying the 
number of characters to read. 


Zs control args 
Can be selected from the same list as described under the 
get_line operation. 


This command reads the next N characters from the file or device 
to which the I/0 switch is attached. The disposition of the 
characters read is the same as described under the get line operation; 
that is, they are written upon user output if the -segment control 
argument is not specified, or stored in a segment if the -segment 
control argument is specified. 
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Operation: put_chars 


ie _call put_chars switchname {string} {-control args} 


where: 


Le string 
may be any character string. 


2s control args 
an be selected fr 
~segment path {length}, -segment path {offset} {length}, 
-sm path {length}, -sm path {offset} {length} 
specifies that the data for the output operation is to be 
found in the segment specified by pathname. The location 
and length of the data may be optionally described with 
offset and length parameters. 


-nnl 
specifies that a newline character is not to be appended 
to the end of the output string. 


-nl 
specifies that a newline character is to be added to the 
end of the output line if one is not present. 

-lines 


Specifies that offsets and lengths are measured in lines 
instead of characters. 


The string parameter and the -segment control argument are 
mutually exclusive. If a string is specified, the contents of the 
String are the data output to the I/O switch. If the -segment control 
argument is specified, the data is taken from the segment specified by 
path, at the offset and length given. If offset is omitted, the 
beginning of the segment is assumed. If length is omitted, the entire 
segment is output. 


If the I/0 switch is attached to a device, this command transmits 
the characters from the string or the segment to the device. If the 
I/O switch is attached to an unstructured file, the data is added to 
the end of the file. The -nl control argument is the default on a 
put chars operation: a newline character is added unless one is 
already present, or the -nnl control argument is specified. 
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Operation: read record, read 


io call read_record switchname N {-control_args} 


where: 

a N 
is a decimal integer greater than zero specifying the size 
of the buffer to use. 

2s control args 


can be selected from the same list as described under the 
get_line operation. 


This command reads the next record from the file to which the I/o 
switch is attached into a buffer of length N. If the -segment control 
argument is not specified, the record (or the part of it that fits 
into the buffer) is printed on user output. If the -segment control 
argument is specified, the record is stored in a segment as explained 
under the get_chars operation. 


Operation: write record, write 


io call write record switchname {string} {-control args} 


— — — 


Lis string 
is any character string. 


23 control args 
may be selected from the same list as described under the 
put chars operation. 


This command adds a record to the file to which the I/O switch is 
attached. If the string parameter is specified, the record is equal 
to the string. If the -segment control argument is specified, the 
record will be extracted from the segment as described under the 
put_chars operation, In either case, the -nnl control argument is the 
default: a newline character is added only if the -nl control 
argument is specified. If the file is a sequential file, the record 
is added at the end of the file. If the file is an indexed file, the 
record's key must have been defined by a preceding seek key operation. 
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Operation: rewrite record, rewrite 


eta ke ee eugt beak meee we ff wee i me te sen n 
io call rewrite record switchname {string} [{-control args} 

where: 

Ls String 


is any character string. 


Bis control args 


May be selected from the same list as described under the 
put_chars operation. 


This command replaces the current record in the file to which the 
I/O switch is attached. The new record is either the string 
parameter, or is taken from a segment, as described under the 
write record operation. The current record must have been defined by 
a preceding read_record, seek key, or position operation as follows: 


read_record 
current record is the last record read. 

Seek key 

Position 
current record is the record preceding the record to which 
the file was positioned. 

Operation: delete record, delete 
io call delete record Switchname 
This command deletes the current record in the file to which the 


I/O switch is attached. The current record is determined as in 
rewrite record above, 
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Operation: position 


io call position switchname type 


where type may be one of the following: 


bof 
sets position to beginning of file 


eof 
sets position to end of file 


forward N, fwd N, £ N 
sets position forward N records or lines (Same as reverse 
N) 


reverse N, rev N, xr N 
sets position back N records (same as forward -N records) 


other 
any other numeric argument or pair of numeric arguments 
may de specified, but its function devends on the I/0 
module being used and may not be implemented for ail I/0 
modules. 


This command positions the file to which the I/0 switch is 
attached. If type is bof, the file is positioned to its beginning, so 
that the next record is the first record (structured files), or so 
that the next byte is the first byte (unstructured files). If type is 
eof, the file is positioned to its end; the next record (or next byte) 
is at the end-of-file position. If type is forward or reverse the 
file is positioned forwards or backwards over records (structured 
files) or lines (unstructured files). The number of records or lines 
skipped is determined by the absolute value of N. 


In the case of unstructured files, the next byte position after 
the operation is at a byte immediately following a newline character 
(or at the first byte in the file or at the end of the file); and the 
number of newline characters moved over is the absolute value of N. 


If the I/0 switch is attached to a device, only forward skips 
(where type is forward) are allowed. The effect is to discard the 
next n lines input from the device, 
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Operation: seek _ key 


io_cali seek key switchname key 
where key is a string of ASCII characters with O!<!length!<!256. 


This command positions the indexed file to which the I/0 switch 
is attached to the record with the given key. The record's length is 
printed on user output. Trailing blanks in the key are ignored. 


If the file does not contain a record with the specified key, it 
becomes the key for insertion. A following write record operation 
adds a record with this key. 


Operation: read_key 


io_ call read_key switchname 


This command prints, on user output, the key and record length of 
the next record in the indexed file to which the I/0 switch is 
attached. The file's position is not changed. 


Operation: read length 


io call read_length switchname 


This command prints, on user_output, the length of the next 
record in the structured file to which the I/O switch is attached. 
The file's position is not changed. 
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Overation: control 


io call control switchname order {args} 


where: 

le order 
is one of the orders accepted by the I/O module used in 
the attachment of the I/0 switch. 

as args 


are additional arguments dependent upon the order being 
issued and the I/O module being used. 


This command applies only when the I/0 switch is attached via an 
I/O module that supports the control I/O operation. The exact format 


of the command line depends on the order being issued and the I/0 


module being used. For more details, refer to "Control Operations 
from Command Level" in the appropriate 1/0 module in the MPM 
Subroutines. If the I/O module supports the control operation and the 


paragraph just referenced does not appear, it can be assumed that only 
control orders that do not require an info structure can be performed 
with the io call command, as anull info ptr is used. (See the 
description of the iox $control entry point and the 1/0 module's 
control operaticn, both in the MPM Subroutines.) 


io call modes switchname {string} {-control arg} 


where: 

Ls string 
is a sequence of modes separated Sy commas. The string 
must not contain blanks. 

aN control arg 


may be -brief or -bf. 


This command applies only when the I/0 switch is attached via an 
I/O module that supports modes. The command sets only new modes 
Specified in string, and then prints the old modes on user output. 
Printing of the old modes is suppressed if the -brief control argument 
is used. 
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If the switch name is user i/o, the command refers to the modes 
controlling the user's terminal. See the I/0 module tty subroutine 
description in the MPM Subroutines for an explanation of applicabie 
modes. 

Operation: find iocb aa 
io call find_iocb switchname 
This command prints, on user output, the location of the control 


block for the I/0 switch. If it does not already exist, the control 
block is created. 


Operation: look_iocb 


io _ call look_iocb Switchname 


This command prints, on user output, the location of the control 
block for the I/O switch. If the I/0 switch does not exist, an error 
is printed. 


io_ call move attach Sswitchname switchname2 


where switchname2 is the name of a.second I/0 switch. 


This command moves the attachment of the first I/0 switch 
(switchname) to the second I/0 switch (switchname2). The original I/0 
switch is left in a detached state. 

Operation: destroy iocb 

io_ call destroy _iocb switchname 

This command destroys the I/0 switch by deleting its control 
block. The switch must be in a detached state before this command is 
used. Any pointers to the I/O switch become invalid. 

Operation: print_iocb 


io call print iocb switchname 
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This command prints, on user output, all of the data in the 
control block for the I/O switch, including all pointers and entry 


variables. 


Summary of Operations 


Usage: io attach switchname modulename {args} 

Usage: io detach switchname 

Usage: io open switchname mode 

Usage: io close switchname 

Usage: io get_line switchname {N} {-control_ args} 

Usage: io get chars switchname N {-control _args} 

Usage: io put_ chars switchname {string} {-control args} 
Usage: io read_ record switchname N {-control _args} 

Usage: io write record switchname {string} {-control _args} 
Usage: io rewrite record switchname {string} {- control_ args} 
Usage: io delete record switchname 

Usage: io position switchname type 


Usage: io seek key switchname key 

Usage: io read key switchname 

Usage: io read length Switchname 

Usage: io control switchname order {args} 

Usage: io modes switchname {string} {-control_arg} 


Usage: io find iocb switchname 

Usage: io Look_ iocb switchname 

Usasces ic move attach switchname switchname2 
Usage: io destroy _iocb switchname 


Usage: io print_ iocb switchname 


where: 
qs Sswitchname 
is the name of the I/O switch. 
Ze modulename ‘ 
is the name of I/O module used in the attachment. 
Ee args 
are any arguments accepted by the I/O module used in the 
attachment. 
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4. mode 
is one of the following modes: 
Stream input, si Keyed sequential input, ksqi 
stream output, so keyed_ sequential” output, ksqo 
stream input_ output, sio keyed, sequential update, ksqu 
sequential input, sqi direct_ input, di- 
sequential output, sgo direct output, do 
sequential input_output, sqio direct_update, du 
sequential update, squ 

ae N 


is a decimal number. 


is any character string. 


they type 

sets the file position. It can be: 

bof forward N 

eof reverse N 

other 
8. Key 

is a string of ASCII characters with Ol<tlength!<!256. 
9% order 


is one of the orders accepted by the I/O module used in 
the attachment of the I/O switch. 


10. control_args 
Can be chosen from the following: 


-segment path {length}, -sm path {length} 

-segment path {offset}, -sm path {offset} 

-segment path {offset} {length}, -sm path {offset} {length} 
=-nnl : 

“nl 

-lines 

-brief, -bf 
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Name: list external variables 


The list external variables command prints information about 
variables managed by the system for the user, including FORTRAN common 
and PL/I external static variables whose names do not contain dollar 
signs. The default information is the location and size of each 
specified variable. 


Usage 


list external variables names {-control args} 


where: 
i names 

are names of external variables, separated by spaces. 
2s control args 


can be chosen from the following: 


-unlabeled common, -uc 
is the name for unlabeled (or blank} common. 


“long, -lg 
prints how and when the variables were allocated. 

~-all, -a 
prints information for each variable the system. is 
managing. 


~no_header, -nhe 
Suppresses the neader. 
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Name: list temp segments 

The list _temp_segments command lists the segments currently in 
the temporary segment pool associated with the user's process. This 
pool is managed by the get_temp segments and release _temp_segments_ 
subroutines (described in the MPM Subroutines). 


Usage 


list_temp_segments {names} {-control_arg} 


wheres: 

tw names 
is alist of names identifying the programs whose temp 
segments are to be listed. 

23 control arg 


is -all (or -a) to list all temporary segments. I£ the 
command is issued with no control argument, it lists only 
those temporary segments currently assigned to some 


program. 
Examples 


To list all the segments currently in the pool, type: 


! list_temp_ segments -all 
5 Segments, 2 Free 
1BBBCdfighgffkkki.temp.0246 work 
IBBBCdfiddfdffkl.temp.0247 WOrk 
'BBBCddffdfffhhh.temp.0253 (free) 


IBBBCdgdgfthftgfsf.temp.0254 (free) 
IBBBCvdvfigvdgvvv.temp.0321 editor 


To list the segments currently in use, type: 


! list _temp_segments 
3 Segments 
!BBBCdfighgffkkkl.temp.0246 WOrK 


!BBBCadffddfdfikl.temp.0247 WOrk 
!BBBCvdvigvdgvvy.temp.0321 editor 
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To list segments used by the program named editor, type: 


on 


list temp segments editor 
1 segment 


!BBBCvdvigvdgvvy.temp.0321 editor 
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Name: page trace, pgt 

The page trace command prints a rece 
other system events within the calling pr 
Usage 


page trace {N} {-control_args} 


where: 
Me N 
Prints the last N system events (mostly page faults) 
recorded for the calling process, Tf N is not specified, 
then all the entries in the system trace list for the 
calling process are printed. Currently, there is room for 
approximately 350 entries in the system trace array. 
rae control _ args 
can be chosen from the following: 
-~from STR, -fm STR 
searched the trace array for a user marker matching STR. 
T£ one is found, printing bégins with it; otherwise, 
printing begins with the first element in the array. 
-long, -lg 
prints full pathnames where appropriate. The default is 
to print only entrynames. 
-no_header, -nhe 
suppresses the header that names each column. The default 
is to print the header. 
-output switch swname, -os swname 
writes all output on the I/0 switch named swname, which 
must already be attached and open for stream_output. The 
default is to write all output on the user output 1/0 
switch. 
~to STR . 
stops printing if a user marker marching STR is found. 
The default is to print until the end of the array. If 
both -from and <-to are specified, the from marker is 
assumed to cccur before the to marker. 
Output 
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The first column of output describes the type of trace entry. An 
empty column indicates that the entry is for a page fauit. The second 
column of output is the real time, in milliseconds, since the orevious 
entry's event occurred. The third column (printed for page faults 
only) is the ring number in which the page fault occurred. The fourth 
column of output contains the page number for entries, where 
appropriate. The fifth column gives the segment number for entries, 
where appropriate. The last column is the entryname (or pathname) of 
the segment for entries, where appropriate. 


Notes 


Since it is possible for segment numbers to be reused within a 
process, and since only segment numbers (not entrynames or pathnames) 
are kept in the trace array, the entrynames and pathnames associated 
with a trace entry may be for previous uses of the segment numbers, 
not the latest ones. In fact, the entry and pathnames printed are the 
current ones appropriate for the given segment number. 


For completeness, events occurring while inside the supervisor 
are also listed in the trace. The interpretation of these events 
Sometimes requires detailed knowledge of the system structure; in 
particular, they may depend on activities of other users. For many 
purposes, the user will find it appropriate to identify the points at 
which he enters and leaves th Supervisor and ignore the events in 


between. 


7 


Typically, any single invocation of a program does not induce a 
page fault on every page touched by the program, since some pages may 
still be in primary memory from previcus uses or use by another 
process, It may be necessary to obtain several traces to fully 
identify the extent of pages used. 


A count value (N) and either the -from or -to control argument 
cannot be specified in the same invocation of the page trace command. 
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Name: print _bind_map 


The print_bind_map command displays all or part of the bind map 
of an object segment generated by version number 4 or subsequent 
versions of the binder. 


Usage 


print_bind_map path {components} {-control_ args} 


where: 


Lie path 
is the pathname of a bound object segment. 


26 components 

are the optional names of one or more components of this 
bound object and/or the bindfile name. Only the lines 
corresponding to these components are displayed. A 
component name must contain one or more nonnumeric 
characters. If it is purely numerical, it is assumed to 
be an octal offset within the bound segment and the lines 
corresponding to the component residing at that offset are 
displayed. A numerical component name can be specified by 
preceding it with the -name control argument (see Deliow). 
If no component names are specified, the entire bind map 
is displayed. 


3% control args 
may be chosen from the following list: 


-long, -lg 

prints the components' relocation values (also printed in 
the default brief mode), compilation times, and source 
languages. 


=-name STR, =-nm STR 
is used to indicate that STR is really a component name, 
even though it appears to be an octal offset. 


-no header, -nhe 


omits all headers, printing only lines concerning the 
components themselves. 
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print link info, p14 


Name: print _link_ info, pli 


The print link info command prints 


for the specified object segments. 


Usage 


selected items of information 


print_link_info paths {-control_ args} 


are the pathnames of object segments. 


where: 

ks paths 

par control args 
can be chosen from 
below.) 


-~length, -lin 
print only the lengths 


the following list. (See "Note" 


of the sections in pathi. 


=Sntry, =—et 
print...only-a. (listing of che -pathi external “detinicions, 
giving their symbolic names and their relative addresses 
within the segment. 

~link, -lk 
print only an alphabetically sorted listing of all the 
Fs £ Y 2 pe) 
external symbols referenced by pathi. 

-long 
prints more information when the header is printed. 
Additional information includes a listing of source 
programs used to generate the object segment, the contents 
of the “comment" field of the symboi header (often 
containing compiler options), and any unusual values in 


the symbol header. 


-header, -he 
prints the header (The header is not printed by default, 
if the -length, -entry, or -link control argument is 
specified.) 
-no_header 
suppresses printing of the header. 
Note 
Control arguments can appear anywhere on the command line and 
apply to all pathnames. 
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print link info, pli 


Example 


{ print _link_info program -long -length 


program 07/30/76 1554.2 edt Fri 


Object Segment >udd>Work>Wilson>program 

Created on 07/30/76 0010.1 edt Fri 

by Wilson.Work.a 

using Experimental PL/I Compiler of Thursday, July 26, 1976 at 21:38 


Translator: PL/I 
Comment: map table optimize 
Source: 


07/30/76 0010.1 edt Fri >user dir dir>work>Wilson>s>s>program.poll 

L27L5/75. 1338.1. edt. Mon >library_ dir_dir>include>linkdcl. incl.pll 

06/30/75 1657.7 edt Mon >library_ dir _dir>inelude>object_info.incl.pll 
10/06/72 1206.8 edt Fri >library dir_ dir>include>source map.incl. pll 
05/18/72 1512.4 edt Thu >library_ dir ~dir>include>symbol_ Dbiock ,inelept 
01/17/73 1551.4 edt Wed >library_ dir dir>include>pll _symbol_ block. er oll 


Attributes: relocatable,procedure,standard 

Object Text Defs Link Symb Static 
Start ¢) 0 3459 3626 3656 3630 
Length LILO 3450 150 36 5215 0 
<ready> 


Also printed is: 


Severity, if it is nonzero. 
Entrybound, if it is nonzero. 
Text Boundary, if it is not 2. 
Static Boundary, if it is not 2. 
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print linkage usage, plu 


Name: print linkage usage, plu 
The print_linkage usage command lists the locations and size of 
linkage and static sections allocated for the current ring. This 


information is useful for debugging purposes or for analysis of how a 
process uses its linkage segments. 


A linkage section is associated with every procedure segment and 
every data segment that has definitions. 


Usage 


print linkage usage 


Note 


For standard procedure segments, the information printed includes 
the name of the segment, its segment number, the offset of its linkage 
section, and the size (in words) of both its linkage section and its 
internal static storage. 
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Name: probe, pb 


asa ammany oe eee =i 4 gg a pat ee ge 


Tne probe command provides symbolic, interactive debugging 
facilities for programs compiled with PL/I, FORTRAN, or “COBOL. Its 
features permit a user to interrupt a running program at a particular 
statement, examine and modify program variables in their initial state 
or during execution, examine the stack of block invocations, and list 
portions of the source program. External subroutines and functions 
may be invoked, with arguments as required, for execution under probe 
control. The probe command may be called recursively. 


Usage 


probe {procedure name} 


where procedure name is an optional argument that gives the symbolic 
name of an entry to the procedure or subroutine that is to be examined 
with probe. It can take the form reference nameSoffset name. I£ no 
procedure name argument is specified, the procedure owning the frame 
in which the last condition was raised is assumed, if one exists; 
otherwise, an error is reported. 


Overview of Processing 


The probe command is generally used to examine an active program 
at points where execution has been suspended by one of the following: 


l. Breakpoint. Execution is temporarily halted at a point 
selected by the user and probe entered directly. Debugging 
requests associated with the breakpoint are automatically 
Carried out and/or requests issued from the user's terminal. 
Program execution can be resumed at the point ot 


interruption. 
2s EYror. An error such as zerodivide or subscriptrange can 
interrupt program execution. After an error message is 


printed, a new command level is established. The user can 
then call probe to examine the state of the program. 


3. Quit signal. A run-away or looping program can be stopped 
by issuing a quit signal. A new command level is 
established and the user can call probe to determine the 
source of the problem. 


In all of these cases, variables of all storage classes 
(including automatic) are accessible. 
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The probe command can also be used to examine a nonactive program 
“~- one that has never been run or that has completed execution -- by 
specifying a procedure name argument in the command line. [In this 
case, the user can examine static variables and the program source. 
However, the most common use is to set breaks before actually running 
the program. 


A program to be debugged with probe must have a standard symbol 
table that contains information about variables defined in the program 
and a statement map that gives the correspondence between source 
statements and object code. A symbol table and statement map are 
produced for the languages supported if the -table control argument is 
given at compilation. {(A program may also be compiled with the 
-brief table control argument, which produces only a statement map. 
The variables of a program compiled in this way cannot be examined 
with probe; however, the user may retrieve information about source 
Statements and where the program was interrupted and also may set 
breakpoints at particular statements.) 


Information about pDrograms being debugged is stored by probe in a 
segment in the user's home directory called Person id.probe where 
Person id is the user's log-in name. This segment is created 
automatically when needed. 


Srobe Pointers 


Three internal “pointers” are used by probe to keep track of the 
program's state. They are: 

source pointer indicates the current source-program statement 

block vointer °° indicates the current block 


control pointer indicates the current control point 


These values are affected by certain probe requests. A user can, 
for example, position the source pointer to a particular statement, 
then list a portion of the source program beginning at that point. 


The block pointer serves two purposes. It identifies the 
procedure, subprogram, or begin block whose variables are to be 
examined. Further, it specifies the stack frame associated with the 
block and is used to distinguish among different occurrences of an 
automatic variable in a recursively invoked procedure. The control 
pointer marks the point at which a program is suspended. 


The initial values of these pointers are determined as described 
below. ff a procedure name argument is given in the command line and 
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if the designated program is active, the control and source pointers 
_ are set to the last statement executed, and the block pointer is set 
to the most recent invocation of the procedure. If the designated 
program is not active, then the control and source pointers are set to 
the entry statement, and the block pointer to the outermost block (but 
with no active frame). 


If no procedure name argument is given and the default rule 
applies (i.e., a condition has been raised), then the procedure in 
which the condition was raised is used. The source and control 
pointers are set to the statement where the condition was raised, and 
the block pointer. to the block containing that statement. 


Similarly, when probe is entered because of a breakpoint 
encountered during the execution of a program, the source and control 
pointers are set to the statement at which the break has been set; and 
the block pointer to the block containing that statement. 


Breakpoints 


A breakpoint causes a temporary interruption of program 
execution, during which debugging operations can be performed. Using 
probe requests, a user can set a breakpoint before or after any 
statement and can associate a list of probe requests with the break. 
A break set after a statement may, in some cases, not be executed due 
to the nature of the code generated for that statement. When the 
break is encountered during execution, probe is entered and the list 
of requests interpreted automatically. These requests might, for 
example, display the value of a variable or alter its value 
(effectively allowing source level patching of the program), tell what 
line was just executed, or cause probe to read a list of requests from 
the terminal to permit the user to interactively examine the state of 
his program. When the request list associated with the break is 
exhausted, the execution of the program is resumed from the point at 
which it was interrupted. 


The implementation of a breakpoint by probe consists of patching 
a call to the probe command into the appropriate location in the 
object segment of the program. As a result, there need not be an 
active invocation of probe for a break to occur; also, breakpoints may 
be set in a program before it is run, while the program is suspended 
by another break, or before a program interrupted by a quit signal or 
error condition has been restarted. 
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Probe Requests 


A probe request consists of a keyword (or its abbreviation) that 
specifies the desired function and any arguments required by the 
particular request, 


A series of requests may be given in the form of a request list. 
Here, individual requests are separated by semicolons or newline 
characters, 


A Single request or a parenthesized request list may be preceded 
by a conditional predicate whose value determines if and when the 
requests it modifies will be executed. 


The following pages present the format and function of each probe 
request. Requests are grouped according to function. Required 
arguments are indicated for each. The syntax and semantics of generic 
arguments such as expressions, procedures, labels, and variables are 
defined under separate headings following the request descriptions. 


The following descriptions first give the name of the request and 
its abbreviated form (if any). This line is followed by the general 
format line(s) of the request. 


value expression 
Value cross-section 


The request "value expression" causes the value of the given 
expression to be displayed. Allowable expressions are variables, 
builtin functions such as addr and octal, and the value returned by an 
external function. The evaluation of expressions is described later 
(following the descriptions of all the requests) under "Evaluation of 
Expressions." 
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Examples: 


value var 

value p -> a.b(j).c 
value addr (i) 
value octal (ptr) 
value function (2) 


The request "value cross-section" is used to display values 
contained in a cross-section of an array. A cross-section is 
specified by giving the upper and lower bounds of one or more 
subscripts, as in: 


value array (1:5, 1) 


The notation 1:5 indicates the range one through five for the 
first subscript. The example above prints array(i,1l), array(2,1), 
scey carvay(5,1). More than one dimension can be iterated; for 
instance, array!l:2,1:2) prints, in order, array(1,1), array(1,2), 
arravc2, 1); ar ravi2;2)-« 


yam let, i 


let variable = expression 
let cross-section = expression 


This request sets the specified variable or array elements to the 
value of the expression. If the variable and the expression are of 
different data tytes3, conversion is performed according to the rules 
of PL/I. Array cross-sections are expressed as shown in the value 


request above. One array cross-section may not be assigned to 
another. : 


Examples: 


let var = 2 

let array (2,3) =i 
let p -> a.5(1:2).¢ 
let ptr = null 
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Because of compiler optimization, the change may not take 
immediate effect in the program, though the value request shows the 
value to oe altered, 
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rocedure (argl, ..., argn) 


This request calls the procedure named with the arguments given. 
Tf the procedure expects arguments of a certain type, those given are 
converted to the expected type; otherwise, they are passed without 
conversion. The value request (see above) can be used to invoke a 
function, with the same sort of argument conversion taking place. If 


the procedure has no arguments, a null argument list, "()", must be 
given. 


Examples: 
call sub ("abc", p -> p2 => bv, 250, addr(}j)) 


call sub noargs () 
value function ("9010"b) 


control Erom pro 
am execution at that point. 
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goto label var transfer to value of label variaois 

goto action (3) transfer to label constant 

goto 29 transfer to statement on iliine 29 of 
current program 

goto $110 transfer to line with label 110 in the 
FORTRAN program 

goto: Se,4 transfer to the statement following the 


current statement 


Because of compiler optimization, unpredictable results may occur 
when using this request. 


or gure -.g 


quire 
This request causes a return to command level. 
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6» continue, ¢ 


continue 


This request restarts a program that has been suspended by a 
break. If this request is issued in any other context, probe-returns 
to its caller (generally command level). 


SOURCE REQUESTS 
i source, sc 


source n 


This request displays one or more statements beginning with the 
Current statement (i.e., the source pointer). If n is not specified, 
one line is printed; otherwise, nn lines are printed. Only executable 
Statements for which code has been generated can be listed; however, 
if a range of statements is requested, intervening text, such as 
comments and nonexecutable statements (for example, declarations), is 
included in the output. 


2. position, ps 


position labei 
position +n 


This request sets the source pointer to the statement indicated 
by label or to an executable statement relative to the current 
Statement as indicated by the value of n and displays it if the user 
is in long mode. If +n is given, the pointer is set forward n 
Statements; if -n is given, th pointer is set back n statements. IE 


no label or offset is given, the statement designated by the control 
pointer is assumed. 


Examples: 

position here set the source ptr to the statement 
labeled here 

position action (3) © to the statement labeled action (3) 

position 2-14 to the statement on line 14 of include 
File 2 of the program 

position +2 move forward two statements in the 
source 

position -5 move back five statements 
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The position request can also be used to search for an executable 
Statement that contains a specified string, using the form: 


position. “string” 


The search begins with the statement following the current 
Statement and continues through the program, if necessary, until the 
Current statement is again reached. If a match is found, the source 
pointer is set to that statement. If the specified string contains a 
quotation mark, it must be doubled when given in the request line. 
Because statements are reordered by the compiler, the search may not 
necessarily find statements in the same order as the source listing of 
the program would indicate. 


= 


Examples: 


position "write (6,10)" locate the statement in the program 
position “str .= *" a" locate str = "a 
position “q+2"; source locate and print the statement 


SYMBOL REQUESTS 


Le stack, sk 


This request traces the stack backward beginning at the ith frame 
nd continuing for n frames. If i is not given, then the trace begins 
with the most recent frame and continues for n frames. If no limits 
are given, the entire stack is traced. The trace lists ail active 
procedures and block invocations (including quick blocks) beginning 
with the most recent. For each block, a frame or level number is 


given, as is the name of any conditions raised in the frame. 


Examples: 


stack trace the whole stack 
stack 2 trace the two most recent frames 
stack 3, 2 trace the third and second frames 


Normally, system or subsystem support procedures are not included 
in the stack trace. These may be included by specifying "all". 
Examples: 


stack all trace the whole stack including all 
support stack frames 
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Stack 5,3 all trace the fifth, fourth, and third 
frames including all support stack 
frames 

2s use, u 


use block 


This request selects the block to be used for subsequent probe 
requests. It may be specified by the name of an entry, a label, or a 
Stack frame number (level i). If no block is specified, then the 
block originally used (when probe was entered) is assumed. The block 
pointer is set to the specified block so that variables in that block 
can be referenced. In addition, the source pointer is set to the last 
Statement executed in the block. In this way, the point at which the 
block exited can be found through use of the source request. 
Acceptable block specifications include: 


procedure name 
label f= 
level i 

-n 


In this context, procedure name is the name of a procedure or 
Subprogram entry point whose frame is desired; its usage is 
essentially the same as if used on the command line. A label denotes 
the block that contains the statement identified oy the label or line 
mumber; for instance, the label ona begin statement denctes that 
begin block. If the label's block is not active, the source pointer 
is set to the statement specified. The block specification level i 
uses the block with level number i from a stack trace; -n uses the nth 
previous instance of the current block, allowing one to move back to a 
previous recursion level. If more frames are requested than actually 
exist, the last one found is used. ; 


Examples: 
use sub use the block that procedure sub 
occupies 
use label use the block that contains the 
statement labeled label 
use level 2 use the second frame in the stack trace 
use -l use the previous instance of the 
current block 
use -999 use the last (oldest) instance 
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When a level is specified, the last trace mode (support 
procedures included or excluded) specified is used to find the level 
requested. 


Sie symbol, sb 


symbol identifier 


This request displays the attributes of the variable specified 
and the name of the block in which its declaration is found. I£ the 
size or dimensions of the variable are not constant, an attempt is 
made to evaluate the size or extent expression; if the value is not 
available, an asterisk (*) is used instead. 


a. where, wh 
where source 


where block 
where control 


This request displays the current value.of one or all of the 
Pointers. Source and control give the statement number of the 
corresponding statement. Block gives the name of the block currently 
being used; if the block is active, its level number is also given. 
If neither source, block, or control appears, the information for ali 
three is given. 

Examples: 

where give the value of all three pointers 

where source give the value of the source pointer 


BREAK REQUESTS 
Le before, b 


before label: request 
before label: (request list) 


This request sets a breakpoint before the statement specified by 
label and causes the given request(s) to be associated with the break. 
If no label is given, the current statement is assumed. If no 
requests are given, a halt is assumed (see the halt request described 
below). 
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When the running program arrives at the statement specified, 
probe is entered before the statement is executed, and associated 
requests are processed automatically. When all requests are done, 
execution of the program resumes at the statement before which the 
Dreak was set. A breakpoint set before a statement takes effect 
whether the statement is arrived at in sequence or as the result of a 
branch or call from some other location. 


Examples: 
before: (value var; value var2) set a break before the current 


statement to display the value of 
the variables var and var2 


before quick: value x . get a break before the statement 
labeled quick 

before set a break containing the halt 
request before the current 
statement 


The request list may extend across line boundaries if necessary. 


2% after, a 


after label: request 
after label: (request list) 


This request is the same as the defore request except tnat the 
Dreak is set after the designated statement. This means that the 
request list is interpreted after the statement has been executed. : 
the statement odranches to another location in the program, the 
Oreakpoint does not take effect; also, in some cases, the break may 
mot be executed due to the nature of the code generated for the 
statement. 


Notice the distinction between two breakpoints in sequence. The 
one that is after statement x is not effective when control is passed 
to statement x+l from elsewhere. The break before statement x+1l does 
take place. 
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oy halt, h 


hale 


This request causes probe to stop processing its current input 
and to read requests from the terminal. A new invocation of probe is 
created with new pointers set to the values at the time the halt 
request was executed. As part of a break request list, it enables the 
user to enter requests while a program is suspended by the break. A 
running program can be halted in this way. A subsequent continue 
request causes probe to resume what it was doing before it stopped; 
for example, Einish a break request list and resume execution of the 
program. 


Examples: 


before 29: halt causes the program to halt at 
statement 29 and allows the user 
to enter probe requests (the 
continue request can be used to 
restart the program) 

halt; value 5b) causes the value of a to be 
printed before the program 
halts; later, after the user 
enters a continue request, the 
value of b is printed, and the 
execution o€ the program ie 


after: (value a; 


ee SD ee et ee am 


resumed 


if 


: reset, x 


reset 

reset at/after/before label 
reset procedure 

reset * 


This request deletes breaks set by the before and after requests. 
When no argument is supplied, reset deletes the current break. With a 
label argument, breaks set before and/or after a statement are 
deleted; with a procedure or asterisk (*) argument, all the breaks in 
a specified segment or all breaks in all segments, respectively, can 
‘be deleted. 
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Examples: 


reset delete the current break 
reset at 34 delete breaks set before and after the 
first statement on line 34 
reset after 34 delete the break set after line 34 
reset sub delete all breaks in sub 
reset * delete all known breaks 
5% status, st 
status 


Status at/after/before label 
Status procedure 
Status * 


This request gives information about breaks that have been set by 
the user. The scope of the requests is similar to reset except that 
status without arguments specifies all breaks in the current program 
(the program containing the statement designated by the source 
pointer). 


Examples: 


status list the breaks set in the current 
program 

Status before label give the break set before the statement 
at label 

status sub list the breaks set in sub 

status * list the procedures that have oreaks 


Set in them 


as pause, pa 


pause 


This request is equivalent to “halt; reset" in a break request 
list. It causes the procedure to execute a break once and then reset 
Lt. If the statement after which the break is set transfers 
elsewhere, the break does not occur and remains set until encountered 
sometime in the future or explicitly reset at some other point. 
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7. step, s 

step 

This request enables the user to step through his program one 
Statement at atime. It sets a break consisting of a pause request 

fter the next statement to be executed (as indicated by the control 

pointer) and resumes the execution of the program as with a continue 
request. 
MISCELLANEOUS REQUESTS 
ie mode 

mode brie 


mode long 


This request turns the brief message mode on or off. [In brief 


mode, most messages generated by probe are shortened and others are 
Suppressed altogether. The default is long. 
2% execute, eé 


execute “string” 


THis request passes one or more Multics command 1li 
represented above by "string", to the command processor for execut: 


a4 acknowledge 


This request causes probe to identi elf by printing “probe” 
on the terminal. It may be used, for example, to determine if a 
called procedure has returned. 
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CONDITIONAL PREDICATES 
ve ea 


if conditicnal expression: request 
if conditional expression: (request list) 


The request or request list is executed if the conditional 
expression is true. The expression must be of the form: 


expression operator expression 


where operator can be <=, <, =, “=, >, OF >=. 


Example: 


if'a < b: let p = addr (4) 


This predicate is most useful ina break request list where it 
can be used to cause a conditional halt. For example, 


before: LE 2 "S "10"bs hale 
causes the program to stop only when z “= "1lO"b. 
2. while, wl 

while conditional expression: request 


while conditional expression: (request list) 


The request or request list is executed repeatedly as long as the 
conditional expression is true. 


Example: 


while p’~= null: (value p -> r.val; let p= p -> r.next) 
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Evaluation of Expressions 


liowabie expressions inciude simple scalar variables, constants, 
and probe builtin functions. The sum and difference of computational 
(arithmetic and string) vaiues can also be used. 


Variables can be simpl identifiers, subscripted references, 
“Structure qualified references, and locator qualified references. 


Subscripts are also expressions. Locators must be offsets, pointer 
variables, or constants. 


Examples: 


running total 
salaries (p => i = 2) 
aso 27-2603) 

Gu Des (2 3) 

X.Y -> var 


Constants can be arithmetic, String. -Sity and pointer. 
Arithmetic constants can be either decimal or binary, fixed or 
floating point, real or complex. Also, octal numbers are permitted as 
abbreviations for binary integers (e.g., 120 = 10). 


Examples: 


a 

105 

45.37 
4.73e10 
Ze Le0%3t 
123456700 


Character and bit strings without repetition factors are allowed. 
Character strings can include newline characters. Octal strings can 
be used in place of bit strings (e.g., "123"0 = "001010011"b). 


tt abc 3g 
"“quote""instring" 
*“LOLO-" 5 
"01234567"90 
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A pointer constant is of the form: 
segment_number|word offset(bit_offset) 


where the segment number and word_offset must be in octal. The 
bit _offset is optional but if given must be in decimal. The pointer 
constant can be used as a locator. 


Pvamniaec-. 
deh SAREE Pr in wd 

21415764 

23217413(9) 

Four builtin functions are provided by probe: addr, null, octal, 
and substr. The function of addr and null is the same as in PL/I: 


addr takes one argument and returns a pointer to its argument; nuli, 
taking no arguments, returns a null pointer. The function octal acts 
very much like the PL/I unspec builtin function in that it treats its 
argument as a bit string of the same length as the raw data value and 
can be used ina similar manner as a pseudo-variable. However, when 
used in the value request, the value is displayed in octal. Data 
items not occupying a multiple of three bits are padded on the right. 
The substr builtin Eunction may .de used as a function of 
pseudo-variable. It takes two or three arguments. The first argument 
must be a character or bit string or a reference to the octal builtin. 
Function; the second and optional third arguments give the offset and 
length of the desired substring as with the PL/I substr builtin 
function: | 


These builtin functions cannot de used if a program variable of 
the same name appears in the block being referenced. (for example, if 
xX and octal are arrays in the same block, then octal (x(2)) becomes a 
reference to the variable octal, not the probe builtin). 
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Examples: 


For the following examples, assume that p is declared as an 
aligned pointer, i as fixed binary initial(-2), and cs as character($) 
initial. (“apcdefgh"*) . 


value addr (i) displays the address of i 
let p = null sets the pointer, p, to null 
value octal (1) displays the storage containing i in 


octal, giving: VW77277 717116 
value substr (cs, 2, 3) displays “pcd" 


let substr (cs, 4, 1)=""_ sets cs to “abc fgh" 


Label References 


A label identifies a source program statement and can be a label 
variable or constant, a line number in source-listing format, or one 
of the following special statement designators: 


sc designates the “current statement” 
eye) Gesignates the statement on whicn the most recent break. 
occurred 


Snumber designates a FORTRAN label 
An optional offset of the form ",s" is also allowed. 


Examples: 


label statement at label 

label _var statement to which label var is set 

17 statement on line 17 of program 

3=14,2 statement 2 on line 14 of include file 
3 

$b Statement at which last break occurred 

Sek Statement after current statement 

$100 FORTRAN statement labeled 100 


Generally, a label can also be the name of a procedure, entry, or 
Subroutine statement. 


= 
~ 


Procedure References 
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A procedure name is an identifier representing an entry variable 
or constant. External reference names, representing entry points not 
Geclared in the current block, can be used. 


Evaluation of Variable References 
When a variable is referenced in a request, probe first attempts 


to evaluate it by checking for an applicable declaration in the 
current block and, if necessary, in its parents. If no declaration is 


found, the list of builtin functions is searched. Finally, when the 
context allows a procedure name, a search is made following the user's 


search rules. 


The block in which a variable reference is resolved can be 
altered by the use request that sets the current block. For example, 
if "value var" displays the vaiue of var in the current block, then 
"use -1; value var" displays the value of var at the previous level of 
recursion. An optional block specification is available for 
referencing variables in other blocks: 


variable [block] 


where Diock is the same as in the use request. The use of blocks in 
this manner does not alter the block pointer. 


Examples: 


var[-1] looks for the previous value of var 

abc(other block] looks in "other block" for abe 

xyz[39] looks in the block that contains line 
39 for xyz 

nem[level 4] looks in the block at level 4 for n.m 

q(2) [sub] looks in the procedure sub for q(2) 


A block specification can be used to qualify a variable reference 
in any context the variable could be used. However, a block 
specification on a label or entry constant is ignored unless the 
relative (-n) format is used and the label or entry is itself used in 
a block specification. In such a case, it is taken to mean the nth 
previous instance of the block designated by the label or entry; that 
is, “var{sub[-2]]" references var in the second previous invocation 
(third on the stack) of sub. 
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Sample Debugging Sessions 


Two extensive examples are given on che following pages to 
illustrate both how probe requests are used and how to get useful 
debugging information out of them. the first example was devised 
principally to demonstrate the application of probe requests. A 
listing of the source of the program, test, is given on the next page. 
The program has been compiled with the -table control argument (line 
1). The sample output follows with an exclamation point (!) denoting 
lines typed by the user. Unless otherwise indicated, line numbers 
referenced in the following paragraphs are from the sample output. 


The user first calls his program (line 5); noticing that it seems 
to be looping, he stops it by issuing the quit signal (line 6). After 
the user invokes probe (line 10), it responds by telling him that the 
internal function fun was executing line 38 when interrupted. Since 
the source pointer was automatically set to that line, the source 
request (line 12) causes the current source statement to be displayed. 
A statement causing an error could be displayed in a similar manner. 


1 test: procedure; 

2 

3 declare. 

4 

5 (1, 31) fixed binary, 

6 1 s structure based (p), 
7 2 num fixed binary, 

3 2b (n refer (s.num)) float binary, 
9 p pointer, n fixed binary, 
10 , sysprint file; 

ii 

12 

130 = Ss 

14 allocate s set (p); 

iS 

16 dol =i. to Sums 

Ly S,0(1) = fun (Cl, 7)3 

18 end; 

£9 put skip list (s.5); 

20 

ZA. do j = S.num to l by -1; 

22 s.6(}j) = fun (-j, -l); 
20 end; 

24 put skip list(s.b); 

25 
26 return; 

27 

28 

29 fun: procedure (b, i) returns (float binary); 
30 

31 deciare 
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32 (b, i) fixed binary; 


34 if b = 0 

35 then return (1); 

36 else do; 

a7 b= b- i; 

38 returm (2**b + fun (b, i)); 
39 end; 


4l end fun; 


44 end test; 
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pll test -table 
PL/I 
er i248° 3.211 26.336 2380 


Cese 


QUIT 
b°1250 52371 -6.702.52. Level 2;,.10 


probe 
Condition quit raised at line 38 of fun. 
source 
return (2**b + fun (5, 12))> 


stack 
Lt command _processor_ 
19 release stack 
9 unclaimed signal 
8 real sdh_ 
- return_to ring 0_ 
6 fun eu te 
5 test 
4 command _processor_ 
8 listen_ 
2 process overseer. 
1 ser init sdmin 


use level 5 


source 
Soa) oS unm ip wy 

value s.num 

5 
position "i = 1 source 

do i= 1 to s.num; 
after: value i 
Break set after line 16 of test. 
quit . 
rol252: 13375 162.394 354 devel: 2340 


wy 
? 


release 
yr 1252 2.126 4.922 19 


test 


oe cede oe oe 


QUIT 
25232069 «650 25 Level. 2.12 


release 
yr 1253 .092 .937 20 


probe test 
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status 
Break after line 16. 
Status after 16 
Break after line 16: value i 
reset at 16 
Break reset after line 16 of test. 
position 34 
source 

if b= 0 

then. return. (1); 

before: halt 
Break set before line 34 of test. 
quit 
yr 1255 2.78) 12.356 333 


test 
Stopped before line 34 of fun. 
value b 
l 
where 
Current line is line 34 of test, 
Using level 6: fun. 
Control at line 34 of fun. 
value i 
l 
c ; 
Stopped before line 34 of fun. 
stack 5 
8 break 
7 fun 
6 fun 
5 test. 
4 command processor _ 
lue b 
0 
value b[-1] 
0 
Value i 
L 
symbol i 
Fixed binary(17,0) aligned parameter 
Declared in fun. 
use test 
value i 
0 
reset 
Break reset before line 34 of test. 
quit 
c 2307 +44.870. -642783: 1544 


Va 


The stack command is then used (line 14) to see in what order 


procedures were 


called. The output shows that procedure test 
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called from command level, and then called fun. While fun was 
executing, a quit signal was issued and estaolished a new command 
level. 


The use request (line 26) sets the block pointer to the outermost 
block of procedure test, and the source pointer to the last statement 
executed in that block -- the statement which invoked uhe function 
ens 


The source request (line 27) is issued to display the current 
Statement (as set above) to determine from which line of the program 
(17 or 27) fun was actually invoked. 


Since the block pointer has also been set, the user can check the 
value of “s.num" with the value request (line 28) and ascertain that 
it is as desired. Since there is no new declaration of “s.num" within 
the procedure fun, the declaration made in the parent block, test, is 
<nown and the value of “s.num" could be displayed without changing the 
block pointer as would be necessary if there were a conflicting 
declaration. 


The user decides that it is worthwhile to trace the value of i. 
Ratner than recompiling his program with a "put statement’ added in a 
Strategic location, probe allows him to set a break containing a value 
request to accomplish the same thing. The user wants to set the break 
after the do statement on line 16 of the program and searches for it 


with th position request (line 31). The source request is used to 
verify that the correct line was found. The after request is used to 
actually set the break (line 33). The quit request (line 35) then 


causes probe to return command level. 


To abort the suspended program test, the user invokes the Multics 
release command (line 38). If he had done this just after issuing the 
quit signal, he could not have used probe to examine automatic 
variables inside the program or to determine where the program had 
Deen interrupted, 


The program is restarted (line 41) but now, after each execution 
of line 16, the break occurs and probe displays the value of i. 
Clearly, it is not being incremented as it should. Since this 
approach is not producing any useful information, the user aborts the 
program and tries to delete the break. The status request is used to 
tell what breaks have been set in the procedure test (line 54), and 
then (line 56) to see the probe request associated with tnat break. 
The break is then deleted with the reset request (line 53). If there 
nad also been a "Break before 16", then the request “reset at 15" 
would have deleted both. 
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The user next decides to examine fun, so he sets a break that 
will halt every time fun is invoked (lines 60 through 64). Looking at 
the listing, he sees that the first statement in fun is on line 34, so 
he sets the source pointer to that statement with the position request 
and sets a break to halt the program. To accomplish the same thing, 
“before 34: halt" could have been used. 


The program is called (line 69) and then halts when the break 
before line 34 is reached. The user displays b and i (lines 71 and 
77), getting the values he expected. The where request is also used 
(line 73) to check on the current state of things. The continue 
request (line 79) restarts fun, which calls itself recursively and 
stops again. The stack request (line 81, showing the last five 
frames) verifies that fact. The user displays the b in the current 
instance of fun (line 87, at level 7) and in the previous one (line 
89, at level 6). Mistakenly expecting the b's at different levels to 


be different, he gets suspicious. The variable i has the value 
expected (line 91), but the symbol command (line 93) shows that it is 
the wrong instance of i -= the parameter to fun, not the loop index. 


To get the correct instance, he must look in the frame belonging to 
the procedure test (line 96) and display that i (line 97). This i has 
been set to 0. The user then realizes his error. The function is 
modifying its argument (the loop index i) on line 37 (line 94). When 
the user has finished debugging the program, the reset request (line 
99) is used to delete the currently active break (the one that just 
eccurred), and the program is aborted with the quit request (line 
10) 


The oreceding example was constructed to give a user a feeling 
for applying probe requests. The following example is taken from an 
actual debugging session uSing probe and illustrates several 
additional techniques available to the user. 


The program of interest is a subroutine, sort strings, that is 
Supposed to sort a character array of arbitrary dimension; the array 
is passed as an argument to the subroutine. Since very large strings 
are being compared, it would be time consuming to exchange the strings 
themselves. Therefore, an array of pointers to the strings (actually, 
the indices of the strings in the original array) is first sorted by a 
simple bubble sort, and the strings moved afterwards into the correct 
order. There are (at least) two bugs in the program as it appears in 
the listing. The next two paragraphs further describe the algorithm 
intended. 


A bubble sort involves making repeated passes over an input 
array, comparing adjacent pairs of values, and interchanging tnem as 
necessary. This moves the larger (smaller) values toward the end of 
the array. The sort only covers that portion of the array that is out 
of order (i.e., up to the element where the final.exchange took place 
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on the previous pass -- all elements following this point are clearly 
correctly arranged). The example below illusccates how a bubble sort 
works in one case. {The hyphen delimits the end of the search.) 


Original First Pass Second Pass Third Pass 


d a a a2 
a oy b a 
Cc -> b -> - -> b 
b = Cc os 
e d d q 
~ e e e 


In the sort strings subroutine (see source listing below), “k" 
determines the last element of the array needing to be sorted. 
Sorting continues until no exchanges occurred during the last pass 
(i.e., until the test, k <= 1, fails). The “order” array contains the 
indices that are actually sorted. 


The reordering method used is to scan for unordered items and 
then move the entire cnain (a replaces 5; 6b replaces c; and c replaces 
a) containing the element. For example: 


Initial Ordering Desired Ordering Movements 
ai e 3 a temp <- 1 (e) temp <- 2 (a) 
2 d 4 le) 1 <= 3 (a) 2 <- 4 (6b) 
3 a 5 c ag Ses, CC) 4 <- temp 
4 D 2 d 5 <- temp 
a C Z e 


All elements that have been moved into the correct location ars 
flagged as naving been moved by setting their order values to -l. 


Source listings of the program and subroutine, named testss and 
sort strings respectively, are given below. 


1 testss: procedure; 

2 

3 f* test caller for sore Strings: */ 

4 

5 declare 

6 

a i fixed binary, sysprint file, | 
8 sort strings entry (character(256) varying dimension(* 
9 array (6) character(256) varying initial 


oe 
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= 10 (-' “prope"= hello", "xray"; “hice”, "det", "ase" 
We)s 
ha 
LZ 
13 call sort strings (array); 
14 do i = 1 to 6; 
15 put list (array (i)); 
16 put skip; 
a end; 
18 
19 end testss; 
1 sort_strings: procedure (strings) ; 
2 
3 declare 
4 
5 Strings character(256) varying dimension(*), 
6 order fixed binary dimension (hbound (strings, 1)), 
f temp character(256) varying, 
8 (i, k, 1, t) Eixed binary; — 
9 
10 
Ed /* initialize order array */ 
12 
3 do i= 1 to hbound (order, 1); 
14 order (i) = i; 
15 end; 
16 
Ly /* perform bubble sort */ 
18 
19 k, 1 = hbound (strings, 1); 
20 do while (k <= 1); 
ZL do i= 2 to k; 
22 l= i- 1; 
‘ 23 if strings (order (1)) > strings (order (i)) then 
c do; 
24 t = order (1); order (1) = order (i); order {i 
\c) = t; 
25 k = 1; 
26 end; 
27 end; 
28 end; 
29 
30 /* move strings into above ordering */ 
31 
32 do i= 1 to hbound (strings, 1); 
33 if order (i) “= -1 then do; 
34 temp = strings (i); 
35 
36 /* follow chain ‘til reach start again */ 
37 
38 do k = i repeat 1 while (k “= -1); 
39 Ll = ofder (kK); 
40 Strings (k) = strings (1); 
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4l order (k) = -1; 
42 end; 

43 strings (1) = temp; 
44 end; 

45 end; 

46 

47 

48. end sort strings; 


The debugging session begins below. Again, an exclamation point 
indicates lines typed by the user. 


——~ 
eo 
See 


ug ! testss 
2. J¢GuL) 
3 QUIT 
4 r 736 6.068 0.1232 9 level 2, 10 
5 
6 ! probe 
7 Condition quit raised at line 21 of sort strings. 
8 ! source ~ 
) do i= 2 to xk; 
1c ! value k 
pee a 
ae ! value l 
pies Z 
First the program testss, used to Lest. ‘ne: “Sore. Strings 


Subroutine, is calied from command level (line 1). When no output is 
produced, the program is aborted by issuing a quit signal, and probe 
is invoked to determine where the program was looping (line 6). 


When probe is entered, it responds by giving the procedure and 
line where execution was interrupted. The source pointer is set by 
default to that line, so that the source request (line 8) may be used 
to display the text of the statement. The output does not indicate 
whether the infinite loop is occurring in the inner (do i = 2 to k) or 
outer (do while (k <= 1)) loop. The value of k (line 11) is 1, which 


-—f7 
implies that the inner loop is not being entered; the value of 1 (line 
13) is also 1 explaining why the outer loop never terminates. 


An examination of the program shows that k and 1 could take on 
these values if elements 1 and 2 are exchanged on a pass with k = 2; 
on subsequent vasses, no exchanges are made (as the inner loop is not 
entered), and the termination condition is never met. What is needed 
is to force 1 to be less than k on ll passes unless an exchange 
actually occurs. This can be done by setting 1 = -1 before attempting 
the inner loop. 
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14 ! before: let 1 = -1 

15 Break set before line 21 of sort strings. 
16 f “quit 

17 r 737 1.217 3.562 97 level 2, 10 
18 

L3 ! start 

20 

24 def 

22 hello 

23 probe 

24 abc 

Zo xray 

26 E730 Oes59 0.13820 


The probe command can be used to modify the value of variables 
either interactively or as part of a break request list. In the 
latter case, the change is made every time the program is executed. A 
breakpoint is set before the current statement (line 21 of the program 
-- the inner loop) to set the value of 1 to -1 with the before request 
(line 14). The quit request (line 16) causes a return to command 
level, and the Multics start command (line 19) restarts the vorogram 
From where it was interrupted. This time output is generated. 
However, the strings are not being sorted correctly. 


27 i probe sort strings 

28 1 position “i = 1L";source 

29 do i= ] to hbound (order, 1); 

30 ! position "i = 1";source 

31 do i = 1 to hbound (strings , 1); 
32 ! before 

35 Break set before line 32 of sort_strings. 
34 ! quit 

35 vr 738 0.218 0.002 14 

36 

o¢ ! testss 

38 Stopped before line 32 of sort strings. 
39 1! symbol order 

40 fixed binary(17,0) aligned automatic dimension(6) 
4l Declared in sort strings. 

42 { value order(1:6) 

43 6 

44 ) 

45 2 

46 4 

47 1 

48 3 


One way to determine whether it is the sorting or ordering 
section of the program that is functioning incorrectly, is to stop the 
program before the ordering section and look at its input, the array 
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"order." The position request (line 28) is an attempt to locate the 
desired statement, but the source request (line 28), used to check 
that the correct line has been found, shows that the wrong one was 
found. The process is repeated (line 30), and the source pointer set 
to the correct line. A break is set (line 32) to cause the program to 
"halt™ at that statement and enter probe. The driving program is 
begun once again (line 37), and sort _strings halts at the desired 
location. The symbol request (line 39) is used to check that the 
correct dimensions are being received for the array order. The value 
request (iine 42) is used to display order(1), ..., order(6}). It can 
be seen that these are the correct values ("abc", in position 6, is to 
be moved to position l, etc.). 


49 ! position 39: source 

50 | Ll = order (k) 
ee) ! after: (value k; value 1) 
32 Break set alter tine 39 of sort. strings. 
a5 ! continue 

54 1 

55 6 

56 6 

a S 

58 s 

59 2 

60 2 

61 = 

62 5 

63 1 

64 1 

65 -1 

66 4 

oF 4 

68 4 

69 -l 

70 nice 

7i def 

72 hello 

73 probe 

74 abc 

fee) xray 

76 r 740 0.602 0.000 0 


Dopears that the sorting code is working properly (with the 
patch in it). Therefore, the reordering of the array is failing for 
some ather reason. The user then begins to trace the exchanges that 
are made. A break is set (lines 49 and 51) to display the values of k 
(the element to which the string is to be moved) and 1 (the element 
from which the string is to be moved) as the program is running. As 
Stated previously, the effect of recompiling the program with a put 
Statement added can be duplicated in this manner. The break is set 
after the line where both values have been determined for the 
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exchange. The continue request (line 53) restarts the program from 
where it was suspended by the break. 


The output shows that extra exchanges are taking place. When k = 
5, the next element on the chain is the first element (1 = 1), and the 
fifth element should therefore be replaced by the copy of the first 
value stored in "temp." It should not be replaced by the current 
first element (the old element 6, “abc"), Nor should the program 
continue to move the undefined element -1 into element 1. 


probe sort strings 
reset. at. 39 
ta Break reset after line 39 of sort_strings. 


~) 
~~ 


80 ! before 39: if order(k) = i: ( 

81 ! let strings(k) = temp 

82 ! let order(k) = -1l 

83 ! goto 42 

84 © ss} 

35 Break set before line 39 of sort. strings. 
86 Y 2qure 

87 r 742 0.280 0.966 56 


For the program to work properly, the movement through the chain 
must stop when the next element is the first (i.e., when order (k) = 
i). The saved value of the first (temp) should then be copied into 
the current element (strings(k)), and the search for additional 
unreordered elements continued. If the user were to recompile the 
program, the following code should achieve the desired effect. 


i) “= -1 then do; 
temp = strings (i); 
=i 


do k repeat 1 while (erder (k) “= i); 
1 = order (kk); 
Strings (k) = strings (1); 
order (k) = -1; 

end; 

strings (k) = temp; 


order (k) = <1; 
end; 


This approach may be checked before recompilation by making a 
slightly more elaborate patch than the one made previously. The probe 
command may be used to place a check for the correct terminating 
condition as the first thing in the loop on k and, if the condition is 
met, cause strings(k) to be set and the loop exited. First the break 
(containing the two value requests) previously set after the statement 
(line 78) is reset. Then a break, containing several requests and 


Not To Be Reproduced A-70 F21 


probe, pb : 


extending across line boundaries, is set (lines 80 through 84) before 
the statement on line 39 of the program. 


88 1 testss 

89 Stopped before line 32 of sort_strings. 
90 { reset 

91 Break reset before line 32 of sort strings. 
92 ! continue 

93 ade 

94 def 

95 hello 

96 nice 

97 prope 

98 xray 

99 . 74302357 1.582 42 

100 

101 ! probe sort strings 

162 ! status 

203 Break before line 39. 

104 Break before line 21. 

105 ! status at 21 

106 Break before line 21: let 1 = -l 
LO i guide 

108 r 744 0.184 1.146 72 


The program is run once again (line 88}, and the break set 
petween the two sections is encountered again. As it is no longer of 
any use, the reset request (line 90), assuming the default of the last 
Dreak encountered, is used to delete the break. The continue request 
(line 92) resumes the execution of the program. This time it works! 


The probe command is invoxed once again. This time the status 
request is used to recall the breaks set, and, hence, the changes to 
be made to the program. Two forms of the status request are used. 
Just "status" (line 102) gives alist of all breaks set in the 
program; “status at line number" (line 105) gives the text of the 
associated break request list. The user can now edit and recompile 
the program and expect it to work correctly. The fee ae breaks 
need not be reset, because a recompilation has the same effect 


ry 
N 
~ 
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Terminology 


active - a procedure is said to be active if its execution is 
ongoing or suspended by an error, quit signal, breakpoint, 
or ‘call. An active procedure should be distinguished from 
one that has never been run, has completed execution, or has 
been interrupted and aborted by a Multics release command. 


automatic storage - a storage class for which space is allocated 
dynamically in a stack frame upon block invocation. AS a 
result, variables of this class only have storage assigned 
to them, and hence a legitimate address and value, when the 
block in which they are declared has an active invocation. 
PL/I variables, by default, belong to this class. FORTRAN 
variables must appear in an “automatic"™ statement in order 
to belong to this class. 


block - corresponds to a PL/I procedure or begin block or FORTRAN 
program or subroutine, and identifies a particular group of 
variadle declarations. 


breakpoint - a point at which program execution is temporarily 
interrupted and probe requests executed. 


invocation - when a procedure-is called recursively, it will 
appear on the stack two or more times, and will have storage 
allocated for it the same number of times. Each instance of 
the procedure on the stack is considered a separate and 
distinguishable invocation of the block. The values of 
automatic variables can be different in different 
invocations of the same block. The most recent invocation 
is the topmost in stack trace. 


level mumber - an integer used by probe to uniquely designate 
each biock invocation (i.e., each entry in a stack trace). 
Level one is the first (least recent) procedure invoked. 
Level number is not necessarily the same as either of the 
numbers given after the word "level" in a ready message. 
The first of this pair gives the count of command levels in 
effect and gives the value n+l, where n is the number of 
programs (or groups of programs) whose execution has been 
Suspended, the second gives the number of stack frames in 
existence and since the probe stack includes quick blocks, 
this number is less than or equal to the level number of the 
last command level in the stack trace, 
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guick block - internal procedures and begin blocks that satisfy 
certain requirements (e.g., are not called recursively, do 
not contain on, signal, or revert statements, etc.) have 
their automatic storage allocated by the blocks that call 
them. Hence, they do not actually have their own stack 
frames, but share the one of the caller. Certain system 
commands, such as trace stack, ignore these blocks. The 
probe command, however, includes them in a stack trace, and 
treats them as if they were the same as any other blocks. 
The quickness of a block may be determined from a program 
listing containing information about the storage requirement 
of the program (produced with the -symbols, -map, or -list 
control arguments). For example, procedure "“quick" shares 
stack frame of external procedure "main". 


stack - if a procedure A calls another procedure 8, then the 
execution of A is suspended until B returns. Le Bin. tira 
calis cC, then this is an ordered list of procedure or 
subroutine calls indicating which program called which other 
program, and which will return to which. This ordered list 
is called the “stack". In probe, a trace of the stack may 
be displayed by use of the stack request. The list is given 
in top-down fashion with the most recently called procedure 


listed first: 


bo 
® 


IN Wd 
Poo 


The numbers are level numbers. 


stack frame - when a block is invoked (that is, a procedure is 
called or a begin block is entered), storage is allocated 
for its automatic variables. The area allocated is called a 
Stack frame and logically corresponds to each entry in the 


Stack, 

Static storage - a storage class for which space is allocated 
once per process, effectively at the time the procedure is 
first referenced. AS a result, variables of this class 


always have a legitimate address and value. Regular FORTRAN 
variables, and those in a common block, have static storade. 
PL/I variables must be explicitly declared. 


Support procedure - a system utility routine that provides 
runtime support for other procedures (e.g., the procedure 


that llocates storage as requested by a PL/I allocate 
statement). 


t- 
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Summary of Requests 


after 


mode 
pause 


position 


quit 
reset 
source 
stack 
status 
step 
symbol 
use 
value 
where 


wnile 


wn 


wl 
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Is 


probe, 


Set a break after a statement. 
Set a break before a statement. 
Call an external procedure. 


Return from 


one 


probe. 

Execute a Multics command. 

Transfer to a statement. 

Stop the program. 

Execute commands if condition is true. 
Assign a value to a variable. 

Turn brief message mode on or ofé. 
Stop a program once. 


Examine a specified statement or locate 
a string in the program. 


Return to command level. 

Delete one or more Dreaks. 

Display source statements. 

Trace the stack. 

Display information about breaks, 
Advance one statement and halt. 
Display the attributes of a variaole. 
Examine the block specified. 

Display the value of a variable. 


Display the value of probe pointers. 


Execute commands wnlle condition is 
true. 
A-74 F21 


de on or off, 


pause pa -Stop a program once. 


position ps Examine a specified statement or locate a string in the 
program. 


quit g Return to command level. 

reset r Delete one or more breaks. 

source sc Display source statements. 

stack Sk Trace the stack. 

status Se Display information about breaks. 
step Ss Advance one statement and halt. 
symbol sb Display the attributes of a variable. 
use u Examine the block specified. 

value vy Display the value of a variable. 
where . wh Display the value of probe pointers. 


while wl Execute commands while condition is true. 


xj 
tw 
I~ 
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Name: profile 


The profile command is a debugging tool used in conjunction with 
the -profile (-pf) control argument of the pll, fortran, and cobol 
commands. The profile command prints information about the execution 
of each statement in the PL/I, COBOL, or FORTRAN program. 


The -profile control argument causes the compiler to generate an 
internal static table containing an entry for each statement in the 
source program; the table entry contains information about the 


Statement as well as a counter that starts out at zero. The counter 
associated with a statement is increased by one each time the 
Statement is executed. The profile command prints and resets these 
counters. 


Usage 


profile paths {-control_args} 


wheres: 

Ls paths 
are the pathnames or reference names of programs whose 
counters are to be printed or reset. 

2. control args 


are selected from the following list. Control arguments 
apply to ali programs whose names appear in the command 
line. 


-print, -pr 

prints the following information for each statement in the 

specified programs: 

Le line number 

Zin statement number, if greater than 1 

en number of times the statement has been executed 

4. cost of executing the statement measured in number of 
instructions executed online plus the number of PL/I 


operators invoked. Each instruction and each 
Operator invocation count as only one unit. 


Dis the names of all the PL/I operators used by this 
statement 
65. total cost for all statements is printed at the end 
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-prief, -b£ 
omits from the statement list statements that have never 
been executed. 


-long, -lg 
includes in the statement list statements that have never 
been executed. 

-reset, -rs 
causes profile to reset to zero all counters associated 
with the specified program. 

Note 
If no control arguments are given, the default control arguments 


are -print and -brief,. 


Examole 


The PL/I program shown below ccunts the number of occurrences of 
one string in another string. It waS compiled with the -profile 
control argument and execute Snce. Notice chat Line numoer and 
statement number (LINE and ST, respectively) of the statement in the 
then clause is the same as the line number and statement number of the 


1 statement itsel 


be Ne - 


rh 


e 


The source code for the program is: 


l example: proc(sl,s2); 

2 e 
3 declare (Sl,S2)  char(*)., ° 
4 (ik) -Eixed. bin, 

5 ioa_ options (variatle); 

6 

f: K = QO; 

8 do i = 1 to length(sl} - length(s2); 

9 if substr(sl,i,irength(s2)) = s2 

10 then k = k + 1; 

aie end; 

a2 

13 Call. toda (a pk) 

14 end example; 


tj 
N) 
I 
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After executing the program once and invoking the profile command 
without any control arguments, the output is: 


LINE ST COUNT cost PROGRAM 
example 
7 1 1 
8 ul 5 
8 8 24 
9 a 56 
9 uf 1 
Lt y 14 
13 i 13+1 (call _ext_out_ desc) 
14 a O+1 (return) 
TOTAL 114+2 
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Name: reset_external variables 


The reset _external variables command reinitializes system-managed 
variables to the values they had when they were allocated. 


Usage 


reset_external variables names {-control_ arg} 


where: 

4 names 
are the names of the external variables, separated by 
Spaces, to be reinitialized. 

Li control arg 
is -unlabeled_common (or -uc) to indicate unlabeled (or 
block) common. 
Note 


A variable cannot be reset if the segment containing 
the nitialization 


information is terminated after the 
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Name : resolve linkage error, rle 


The resolve linkage error command is invoked 


linkage fault after a process encounters a linkage error. 


locates the virtual entry specified as an argument 


located the specified virtual entry. 


Usage 


resolve linkage error virtual entry 


where virtual_entry is a virtual entry specifier. 


Notes 


For an explanation of virtual entries, see the description of 


cv_entry_ subroutine. 


Examples 
' myprog 
Error: Linkage error by >udd>m>vv>myprogi123 
referencing subroutineSentry 
Segment not found. 
vr 1234 2.834 123.673 980 level 2, 26 
! rle mysubSmysub entry 
r 1234 0.802 23.441 75 level 2, 26 
! start 
ee. Myprog is running 
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satisfy the 
The program 
and patches the 
linkage information of the process so that when the start command 
issued the precess continues as if the original linkage 


is 


fault had 


the 
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Name: run_cobol, rc 


The run_cobol command explicitly initiates execution of a COBOL 
run unit in a specified “main program". This command is not needed to 
execute COBOL object programs on Multics; it is used to simulate an 
environment in which traditional COBOL concepts may be easily defined. 


This command cannot be called recursively. 


Usage 


run_cobol name {-control args} 


i. name 


2 


is the reference name or pathname of the “main program™ in 


which execution is to be initiated. Tf a pathname is 


given, then the specified segment is initiated 


with a 


reference name identical to the entryname portion of the 
pathname. Otherwise, the search rules are used to locate 


the seament. TE the name specified in the 


PROG-ID 


Statement of the COBOL program (i.e., the entry point 


name) is different From ¢t 
object seqment, then the na 

the form ASB where A is the 

the segment and B is the PROG-ID as 
IDENTIPICATION DIVIS -t ro 


i ee ee ee ee ww a ¥ 


= 


defined 
za 


ce control args 
can be chosen from the following: 


-cobol switch N, -cs N 


the current reference name of the 
nm 


7 <4 ’ - 
me specified here must 


hw see 
we if 


pathname or reference name of 


in the 


sets one or more of the eight COBOL-defined “external 
switches" on, where N is a number from 1 to 8 (or a series 
of numbers separated by spaces) that corresponds to the 
numbered external switch. At the outset of the run unit, 


the default setting of these external switches 
(The eight external switches are defined in the 
COBOL Reference Manual, Order No.!AS44.) 


“no_stop run, -nsr 
avolds establishment of a handler for the 
condition. (See "Notes" below.) 


-sort dir patn, ~sd path 


1S OL i; 


stop_run 


specifies the directory to be used during execution of 
this run unit for temvorary sort work files. Le TALS 
control argument is not specified, the process directory 


is assumed. 


=Ssort file size N;, sts Nn 


— 


is the floating point representation of the estimated 
average size in characters of the files to be sorted 
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during execution of this run unit. This information is 
used to optimize sorting. If not specified le6 is assumed 
(i.e., one million characters). 


Notes 


This command enables the user to explicitly define and start 
execution o£ -a@ COBOL run: -wnit.. A rum -unit is ‘either explicitly 
Started by the execution of the run_cobol command or implicitly 
Started by the execution of a COBOL object program either by 
invocation from command level or from acall by another program 
written in COBOL or another language. A run unit is stopped either by 
the execution of the STOP RUN statement in a COBOL object program or 
by invocation of the stop cobol_run command. For the duration of time 
after a run unit is started and before it is stopped, it is said to be 
active. All COBOL programs executed while a run unit is active are 
considered part of that run unit. 


A run unit is a subset of a Multics process; it is stopped when 
the process is ended. Also, when all programs contained in a run unit 
are cancelled, the run unit is stopped (refer to the 
cancel cobol program command). Only one run unit may be active at any 
given time in a process; thus, the run_cobol command cannot be invoked 
recursively. Additionally, if a run unit has been started implicitly 
(as described above), the run_cobol command may not be used until that 
run unit has been stopped; i.e., the run_cobol command does not 
terminate a currently active run unit. 


The explicit creation of a run unit with the run_cobol command 
performs the following functions: 


As Establishment of a "main program", i.e., a program from 
which control does not return to the caller. The EXIT 
PROGRAM statements, when encountered in such a program, have 
no effect, as required in the. COBOL. derinitzion, An 
implicitly started run unit has no “main program". The EXIT 
PROGRAM statement in all programs contained in such a run 
unit always causes control to be returned to the caller, 
even if the caller is a system program, e.g., the command 
processor, 


2% Setting of the COBOL external switches. These switches are 
set to: off unless otherwise specified by the -cobol switch 
control argument. 


om User control of the action taken when a STOP RUN statement 
is executed in a COBOL object program. The action normally 
taken for STOP RUN is cancellation of ali programs in the 
run unit, closing any files left open. After this has been 
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done, the data associated with any of the programs is no 
longer available, Thus in a debugging environment, it may 
be useful to redefine the action taken for STOP RUN. When 
the run unit is explicitly initiated with the run_cobol 
command, the STOP RUN statement causes the signalling of the 
stop _run condition for which a handler is established that 
performs the normal action described above. If the 
-no_ stop run control argument is specified, the handler is 
not established, thus allowing the user to handle the signal 
himself using other Muitics commands. ff the user has not 
provided ahandier himself for stop run and specifies the 
-no_stop run control argument, an unclaimed signal results. 


The name given in the run_cobol command need not be a COBOL 
object program. & may be a program produced by any language compiler 
that provides a meaningful interface. with COBOL programs (e.g., PL/I, 
FORTRAN) . 


Refer to the following related commands: 


display _cobol_run_unit, der 
stop _cobol run, scr 
cancel cobol program, ccp 


Not To Be Reproduced A-83 eens 


set fortran common, sfc 


Name: set _fortran_common, sfc 


The set _fortran_common command allocates and initializes all 
FORTRAN common blocks referenced by the specified FORTRAN object 
segments. The maximum declared length of a common block (of all those 
found in the list of FORTRAN object segments) is used for the 
allocation and initialization. This command can therefore be used to 
Guarantee that the correct common block storage is allocated and 
initialized prior to a FORTRAN run. (If the user left it to the 
dynamic linker, the first reference to the common block would cause it 
to be allocated and initialized as declared in the referencing 
program. This program might not include the necessary initialization 
information.) The set _fortran_common command can also be used to 
reinitialize the common blocks referenced by the specified object 
segments, although it will not reinitialize any local storage such as 
Static or automatic variables. 


Usage 
set.fortran_common paths {-control arg} 

where: 

dee paths 
are the pathnames of the FORTRAN object segments whose 
common blocks are to be allocated and (re)initialized. 

Ze control arg 
can be -long (-1g) indicating that warning messages are to 
be printed. Normally, all warning messages are 
suppressed, Warnings are printed if the common block is 
already allocated with a smaller size. 

Notes 


A FORTRAN obDject segment is either a segment created by one of 
the Multics FORTRAN compilers or is a seqment created by the binder 
and contains at least one component that was created by one of the 
Multics FORTRAN compilers. 


Only common storage is affected by this command, Local variables 
are not (re)initialized. 


Common blocks without data initialization information are set to 
binary zeros. 
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Tf the common block is already allocated, its contents are 
reinitialized and the prior contents are lost. 


A warning is always printed if different initialization values 
are encountered in the set of specified object segments, 
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Name: set _ system_storage 


The set_system storage command establishes an area as the storage 
region in which normal system allocations are performed. 


Usage 


Set_system_storage {virtual_ptr -control_arg} 


where: 
1. virtual ptr 
ls a virtual pointer to an initialized area. The syntax 
of virtual pointers is described in the cv_ptr_ subroutine 
description. This argument must be specified only if the 
~system control argument is not supplied. 
Ze control arg 
is -system to specify the area used for linkage sections. 
This control argument must be specified only if 
virtual ptr is not specified. 
Notes 
To initialize or create an area, refer to the description of the 
Create area command. 
The apea.-must be set. up as either: zero on free or zero on alioc. 


It is recommended that the area specified be extensible. 


Examples 
The command line: 
set_system_storage free Sfree_ 


places objects in the segment whose reference name is free at the 
offset whose entry point name is free . 
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set svstem storage 


The command line: 
set system storage my_seg$ 
uses the segment whose reference name is my seg. The area is assumed 


to be at an offset of OQ in the segment. The segment must already 


exist with the reference name my seg and must be initialized as an 
area. 


The command line: 
set system storage my _ seg 


uses the segment whose (relative) pathname is my_seg. The segment 
must already exist. 
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Name: set _user_ storage 

The set_user_ storage command establishes an area as the storage 
region in which normal user allocations are performed. These 
allocations include FORTRAN common blocks and PL/I external variables 
whose names do not contain dollar signs. 


Usage 


set_user storage {virtual ptr -control_ arg} 


where: 

1. virtual ptr 
is a virtual pointer to an initialized area. The syntax 
of virtual pointers is described in the cv_ptr_ subroutine 
description. This argument must be specified only if the 
~system control argument is not specified. 

2% control arg . 
LS =syStem to specify the area used for linkage secticns. 
This control argument must be specified only if 
virtual ptr is not specified. 

Notes 


To initialize or create an area, refer to the description of the 
create area command. 


The area must be set up as either zero_on_free or zero _on_alloc. 


It is recommended that the area specified be extensible. 


Examples 


The command line: 
set_user storage free $free_ 


places objects in the segment whose reference name is free at the 
offset whose entry point name is free . 
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set user storage 


The command line: 
set_user_ storage my seg$ 
uses the segment whose reference name is my seg. The area is assumed 


to be at an offset of O in the segment. The segment must already 


exist with the reference name my_seg and must be initialized as an 
area, 


The command line: 
set_user_ storage my_ seg 


uses the segment whose (relative) pathname is my_seg. The segment 
must already exist. 
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Name: stop cobol_run, scr 


The stop cobol run command causes the termination of the current 
COBOL run unit. "Refer to the run_cobol command for information 
concerning the run unit and the COBOL runtime environment. 


oe OS 


stop cobol run {-control arg} 


where the control arg may be -retain_data or -retd to leave the data 
Segments associated with the programs composing the run unit intact 
for debugging purposes. (See "Notes" below.) 


Notes 


The results of the stop _cobol_ run command and the execution of 
the TOP RUN statement from within a COBOL program are identical. 


Stopping the run unit censists of cleaning up all files that have been 
opened during the execution of the current run unit, and ensur 


. 
3 whan 
wa be oe we SS IUKL 2G that 


the next time a program that was a component of this run unit is 
invoked, its data is in its initial state. 


To maintain the value of all data referenced in the run unit in 
its last used state, the -retain_data control argument should be used. 


Refer to the related commands: 


display cobol_ run_unit, dcr 
cancel cobol program, ccp 
run_cobol, rc 
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Name: trace 


The trace command is a debugging tool that lets the user monitor 
all calls to a specified set of external procedures. The trace 
command modifies the standard Multics procedure call mechanism so that 
whenever control enters or leaves one of the procedures specified by 
the user, a debugging procedure is invoked. The user can request the 
following: 


Ls Print the arguments at entry, exit, or both. 

2 Stop (by calling the command processor) at entry, exit, or 
both. 

3s Change the frequency with which tracing messages are printed 


(e.g., every 100 calis, after the 2000th call, only if the 
recursion depth is less than five, etc.). 


4. Execute a Multics command line at entry, exit, or both. 
54 Meter the time spent in the various procedures being 


monitored. 


Use of the trace command is subject to the following 
restrictions: 


Ls Only external procedures compiled by PL/I or FORTRAN can be 


traced. 
2% Ring 0 or gate entries cannot be traced. 
ce Incorrect execution results if the traced procedure looks 


back a fixed number of stack frames, ¢.g., cu_$arg_ptr 
cannot be traced. 


4, Only 100 procedures can be traced at one time. Up to 16 
locations can be watched at one time. 


a The procedure being traced and the trace package itself must 
share the same combined linkage segment. 


Bs A procedure in a bound segment can only be traced if its 
entry point is externally available. 

Usade 

eee 


trace {-control_args} names 


3 | 
No 
ia 
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where: 


Ly names 
is a pathname or reference name. The reference name or 
entry portion of a pathname is used in the trace table. 
(See "Notes" below.) 


2. control_args 
apply to the namei arguments that follow, and, if 
applicable, change the current value in the trace control 
template (TCT). (See "Notes" below.) Control arguments 
may be chosen from the following: 


-after N 
calls the command processor after calling the traced 
procedure every N times (initial value!=!0: do not call). 


-argument N, -ag N 
prints the arguments every Nth time the procedure is 
entered (initial value!=!0: do not print). 


-before N 
calls the command processor before calling the traced 
procedure every N times (initial value!=!0: do not cali). 


-brief, -b£ 
prints a short form of the monitoring information. 


-depth N, -dh N 
monitors to the maximum recursion depth of N (initial 
valuet=!0: no limit). 


-every N, -ev N 
monitors every Nth call (initial value!l=!1). 


-execute STR, -ex STR 
executes the Multics command line specified by the string 
STR whenever the procedure is monitored (initia 
Value!=!"": no command). 


-first N, -ft N 
starts monitoring on the Nth call (initial value!=!1). 


-govern STR, -gv STR 
limits/does not limit the recursion level for a procedure, 
where STR can be the String on or off (initial 
value!=!off). See “Recursion Limiting” below. 


-in 
prints the arguments only on entry (initial value!t=!yes). 
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-~inout 
prints the arguments on both entry and exit (initial 
value!=!no). 


~io_switch STR, -is STR 
changes the switch for output to the switch specified by 
STR. (See “Changing Output Switch" below.) 


~last N, -1t N 
stops monitoring after the Nth cali (initial 
value!=!9999999999) . 


-long, -lg 
prints the long form of the monitoring information. (For 
use after the -brief control argument to restore the long 
form.) 


“Meter STR, -me STR 
meters/does not meter the time svent in the procedure, 
where STR can be the string on or Gre -Cinieias 
valuel=!off). See "Metering" below. 


-out 
prints the arguments only on exit (initial va 


-off entryname 
stops monitori 
remains in th 
counted. 


-on entryname 
resumes monitoring the specified procedure. This control 
argument is used after the -off control argument. 


-remove entryname, -rm entryname 
removes the specified procedure from the trace table. 
Tracing can be removed at any time. 


-reset entryname, -rs entryname 
sets the number of calls and recursion depth of the 
specified procedure to zero. 


=return value. STR, =tv STR 
prints/does not print the return value on exit, where STR 
can be the string on or off (initial value!l=!off). This 
control argument assumes the entry is a function. 


-status *, -st * 


prints the procedures being monitored and their counters. 
(See "Notes" below.) 
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-status entryname, ~st entryname 
prints the trace parameters and counters for the procedure 
specified by entryname. (See "Notes" below.) 


~stop_proc path, -sp path 
changes the procedure that is called for stop requests 
Erom the command processor to the procedure specified by 
path. To reset the stop procedure, issue this control 
argument with no path argument. 


~subtotal, -stt 
prints and does not clear the metering statistics. 


-~template, -tp 
lists the trace control template. 
Notes 
The procedure whose pathname is given in the command line is added 
to the trace table with the tracing parameters from the trace control 


template (TCT). Tf the procedure is already in the table, the 
counters are reset and the current parameters in TCT are used. 


For control arguments that affect procedures being traced, the 
argument is an entryname or an asterisk (*). If an entryname is used, 
the control argument applies to that procedure. If an asterisk is 
used, the control argument is applied to all entries in the trace 
table, All control arguments that affect the TCT must have a number 
argument (indicated by N above). 


Examples 


The command line: 
zrace -ag 1 -inout test 


prints the arguments for test on entry and exit. 


The command line: 

trace -ag 2 -in -depth 6 test 
prints the arguments for test every second time test is entered up to 
a recursion depth of six, i.e., 2, 4, 6. 

The command line: 

trace ~-govern on test 
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prints the arguments of test each time test is called with a new 
maximum recursion depth. The trace procedure calls the command 
processor every time the recursion depth is a multiple of 10. 


The command line: 
trace -st * -tp 


lists the procedures in the trace table and prints the values of the 
trace control template. 


Message Format 


The message printed when control enters a procedure can appear in 
any one of several formats, depending on the setting of the brief 
switch and the status of the calling procedure. Tf the calling 
procedure is unbound or occurs in a bound segment containing a 
bindmap, the message takes the form: 


Call 4.1 of alpha from betal127, ap = 204/10746. 


This is the fourth call of procedure alpha, which is at rec 
level 1. The call comes from location 127 in component beta, a 
argument list is at 204{10746. If the procedure making the call 
a Bound segment that does not contain a bindmap, the message take 
LOM: 


Call 4.1 of alpha from bound_gamma|437 (beta), ap = 204110746. 


The name in parentheses may not always be available and may be omitted 


im some cases. If the user has requested the brief output mode, the 
message is shortened to: 


Call 4.1 of alpha. 


When tracing is requested for a procedure, the parameters for that 
entry are taken from the trace control template (TCT). If the user 
does not alter the values in the TCT, the initial default values are 
used (see below). The initial values in the TCT specify that every 
call should be monitored. 


ny 
h 
~ 
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Trace Control Template 


As mentioned earlier, the trace table entry holds a number of 


parameters for each procedure to be traced. The values of the 
parameters are determined by the contents of the TCT at the time the 
table entry is filled in. These parameters are used in conjunction 


with N (the number of calls to the traced procedure in this process) 
and R (the current recursion depth) to control when and how the 
procedure should be monitored. The execution count (N) is set to 0 
when tracing is first started and is incremented by 1 every time the 
traced procedure is called. The recursion depth (R) is set to 0 when 
tracing is first started and is incremented by 1 every time control 
enters the traced procedure and is decremented by 1 every time control 
leaves the traced procedure. 


Let: 
D = the maximum recursion depth to be monitored (-depth) 
F = the number of the first call to be monitored (-£first) 
L = the number of the last call to be monitored (~last) 
E = how often monitoring should occur (-every) 
B = the number of times the procedure is called before trace 
stops at entry to the traced procedure (-before) 
A the number of times the procedure is called before trace 
stops at exit from the traced procedure (-after) 
AG = the number of times the procedure is called before trace 


prints the arguments of the traced procedure (-argument) 
=a bit that is “1"b if the tracing procedure should print the 
arguments of the traced procedure when control goes into the 
traced procedure (-in) 
O = a bit that is “"1l"b if the tracing procedure should print the 
arguments of the traced procedure when control goes out of 
the traced procedure (-out) 


Hi 
t 


A call is monitored and the tracing procedure is called if, and 
only 15 


F <= N <= L 
R <= D 
mod(N,&) = 0 


If AG “= 0, mod(N,abs(AG)) = 0, and I = "“"l1"b, trace prints the 
values of the arguments (if any) being passed to tne traced procedure. 
All of the arguments are listed when AG < 0. If AG < 0, the procedure 
is assumed to be a function and the value of the last argument is 
printed after the procedure returns. 
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If B “= 0 and mod(N,B) = 0, the monitoring procedure prints 
"Stop" and calls the command processor (or a user-set procedure if the 
-stop proc control argument was used). This call occurs before the 
procedure being traced has created its stack frame. 


After control leaves the traced procedure, trace prints a line of 
the form: 


Return N.R from alpna. 


If AG “= O and mod(N,abs(AG)) = 0, then all of the arguments of 
the traced procedure are printed if O = “"1"b; otherwise, if AG < 0, 
the value of the last argument (assumed to be the value of the 
function) is printed. 


Finally, trace ceils the command processor. FE. the =stop: proc 
control argument was given, a procedure set by the user is called. 
This call occurs after the stack frame of the procedure being traced 
has been destroyed. 


Metering 


The trace command can be used to meter the execution of a 
specified set of procedures. If the metering feature is being used, 
trace does not call the debugging procedure when control enters a 
procedure being traced; instead, it determines the current time and 
the virtual CPU time used, and the number of page faults taken by the 
user's process before control enters and after control leaves the 
traced procedure. This information is used to compute the real time 
and CPU time used, and the number of page faults taken by the traced 
procedure on a local and global basis. The globai CPU time is the 
time spent in the procedure including the time spent in any procedures 
that it calls. The local CPU time does not include the time spent in 
any traced procedure called by the procedure, but it does include time 
Spent in called procecéures that are not being traced. The local and 
global versions of real time and page faults are calculated ina 
Similar manner. Metering is only done when the first, last, every, 
and depth tracing conditions are satisfied. 


The control argument: 


=Neter on, “~Mt on 
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sets the metering switch in the TCT; any procedures added to the trace 
table or that have their table entries updated after this argument is 
used are metered. 


The control argument: 


turns off the metering switch in the TCT; any procedures currently 
being metered continue to be metered. 


The control argument: 


-total 


causes trace to print the metering statistics of all procedures in tre 
trace table. The output gives the number of caiis (#CALLS), giobo:al 
CPU time (GCPU), global real time (GREAL), global page waits (GPWS', 
local CPU time (LCPU), local real time (LREAL), local page wai:s 
(LPWS), and the usage percentage (%USAGE) based on local CPU time, :7£ 
all the procedures being metered. The metering statistics are set to 
0 after they are printed. 


The control argument: 


-subtotal, -stt 


prints the same information as the -total control argument, but de?zs 
not clear the statistics. 


ry 
ie) 
te 
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Recursion Limiting 


The control argument: 
-govern on, -gv on 


sets a bit in the TCT that causes recursion limiting to be in effect 
for any procedure subsequently added to the trace table. When the 
governing feature is used, the depth control parameter is ignored and 
trace prints the call message only when the recursion depth of the 
traced procedure reaches a new, maximum depth. Each call message has 
a recursion depth one greater than the previous call message. [n 
addition, trace cails the command processor (or a user-defined 
procedure if the -stop proc control argument was used) whenever the 
recursion depth is a multiple of 10. Return messages are not printed. 
This feature enables the user to find and limit uncontrolled 
recursion; it can be very useful in finding the procedure(s) 
responsible for fatal process error. 


The control argument: 
“govern off, -gv off 


turns off the governing switch in the TCT; any procedure currently 
being governed continues to be governed. 


Watch Facility 


The trace command has an optional watch facility in which trace 
watches the contents of a set of previously specified memory cells. 
The cells are checked at every entry to and every exit from every 
traced procedure. As long as the values in the locations being 
watched remain the same, no action is taken and no tracing messages 
are printed. The tracing message is printed as soon as trace finds 
that any of the locations being watched has had its value changed. 
This can be found either at entry to or exit from the traced 
procedure. When any value changes, the tracing message is preceded by 
lines that give the new values of all of the locations that nave 
changed, and the command processor (or a user-set procedure if the 
-stop proc control argument was used) is called even if the A or B 
conditions are not met. When execution continues, the locations that 
nave changed are watched with the new value being used in subsequent 
checks. This feature can be very useful in determining which of the 
user's procedures has incorrectly modified a word of storage. 
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The control argument: 
-watch STR, -wt STR 


causes all procedures being traced to watch for achange in the 
Current contents of the memory word(s) specified by the string STR. 
This string, specifying the lacation, can consist of a single address 
Specification or a series of address specifications separated by 
blanks and surrounded by quotes. If an address specification does not 
contain a vertical bar (|), it is taken to be an octal number giving a 
lecation in the stack; otherwise, it is taken to be a segment number 
and offset in octal in the standard form, e.g., segment_numberloffset. 


The control argument: 
-watch off, -wt off 
turns off the watch facility. 


The watch facility differs from other trace facilities in that 
there is a single table of locations being watched that is used by all 
procedures being traced. When the -watch control argument is 
processed, the new location(s) Specified replace any locations 
Currently in the watch table. There is no provision made for removing 
a Single location from the watch table; the user must reissue a watch 
request that omits the location to be removed from the table. 


Command Execution 


The command execution facility of trace allows the user to 
Specify a Multics command line to be executed whenever the trace 
debugging procedure is called. The trace procedure calls the command 
processor with the specified string after printing the tracing 
message, but before the stop request causes the command processor to 
be called. 
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The control argument: 
-execute string 


sets the execution string parameter in the TCT. Since string is a 
single argument, it must be enclosed in quotes if it contains any 
spaces. The execution parameter in the TCT is turned off if string 
has zero length (-execute ""). The following line: 


trace -ex time test 


causes trace to execute the time command before and after test is 
called. 


Changing Qutput Switch 


All of the messages from the trace command that may 
while actually monitoring procedures are normally wr 
user i/o switch so that trace can conveniently be used wi 
that change the attachment of the normal switch, user 
control argument: 


-i0 switch STR 


causes trace to write further monitoring output on the switch 
specified by STR, which must already be attached and opened for 
Stream output. 
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Name: trace stack, ts 


The trace stack command prints a detailed explanation of the 
Current process stack history in reverse order (most recent frame 
first)... For each stack frame, all available information about the 
procedure that established the frame (including, if possible, the 
source statement last executed), the arguments to that (the owning) 
procedure, and the condition handlers established in the frame are 
printed. For a description of stack frames, see “Multics Stack 
Segments" in Section!IV of the MPM Subsystem Writers‘ Guide. 


The trace stack command is most useful after a fault or other 
error condition. If the command is invoked after such an error, the 
machine registers at the time of the fault are also printed, as well 
as an explanation of the fault. The source line in which it occurred 
can be given if the object segment is compiled with the -table option. 


Usage 


brace stack {-control args! 


where control _ args can be selected from the following: 


-brief, -bf 
Suppresses listing of arguments and handlers. This 
control argument cannot be specified if -long is also 
specified as a control argument. 


-long, ~lg 
prints octal dump of each stack frame. 


-depth N, -dh N 
dumps only N frames. 


Output Format 


When trace stack is invoked, it first searches 
backward through the stack for a stack frame containing 
saved machine conditions as the result of a signalled 
condition. If such a frame is found, tracing proceeds 
backward from that point; otherwise, a comment is printed 
and tracing begins with the stack frame preceding 
trace stack. 


If a machine-conditions frame is found, trace stack 
repeats the system error message describing the fault. 
Unless the -brief£ control argument is specified, 
trace stack also prints the source line and faulting 
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instruction and a listing of the machine registers at the 
time the error occurred. 


The command then performs a backward trace of the 
Stack, for N frames if the -depth N argument was 
specified, or else until the beginning of the stack is 
reached. 


For each stack frame, trace stack prints the offset 
of the frame, the condition name if an error occurred in 
the frame, and the identification of the procedure that 
established the frame. If the procedure is a component of 
a bound segment, the bound segment name and the offset of 
the procedure within the bound segment are also printed. 


The trace stack command then attempts to locate and 
print the source line associated with the last instruction 
executed in the procedure that owns the frame (that is, 
either a call forward ora line that encountered an 


error). The source line can be printed only if the 
procedure has a symbol table (that is, if it was compiled 
with the -table option) and if the source for the 
procedure is available in the user's working directory. 
If the source line cannot be printed, trace stack prints a 


comment explaining why. 


Next, trace stack prints the machine instruction last 
executed by the procedure that owns the current frame. If 
the machine instruction is acall toa PL/I operator, 
trace stack also prints the name of the operator. If the 
instruction is a procedure call, trace stack suppresses 
the octal printout of the machine instruction and prints 
the name of the procedure being called. 


Unless the -brief control argument is specified, 
trace stack Lists the arguments supplied to the procedure 
that owns the current frame and also lists any enabled 
condition, default, and clean-up handlers established in 
the frame. 


LE the ~long control ar 
trace stack then prints an octal d 
with eight words per line. 
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Example 


After a fault that reenters the user environment 2nd 
reaches command level, the user invokes the trace stack 
command. 


For example, after quitting out of the list command, 
the following process history might appear: 


! list 
Segments=8, Records=3 
rew Q mailbox 
row 
QUIT 
trace stack 
quit In ipe $block|156 
(>system_library_1>bound_command_loop |156) 
No symbol table for ipc_ 
156 400010116100 cmpg pr4{10 


Machine registers at time of fault 


pro (ap) 26314656 pll_operators Soperator table|162 
(external symbol in separate nonstand. 


text section) 


prl (ab) 1031264 ses|264 

pr2 (bp) 14])22200 as_linkage|12200 

pr3 (bb) 1123/0 tc_datalo 

pre4 (lip) 25312250 !BBBJIGJFKPBWCNZ.area.linker| 2250 
(internal staticl0O for ipc_) 

pr5 (1b) 244|3614 stack 4/3614 

pr6 (sp) 244|3500 ~. stack 413500 ( -> “kcpMbLH +0000000") 

pr7 (sb) 244/{0 stack 4|0 

x0 73 nae 0 KZ 0 X¥3 600000 

x4 0 x5 32 x6 3033 we 4 


a 000000000000 q 000009000004 e090 
Timer reg - 1746005, Ring alarm reg - 0 


SCU Data: 


4030 400270250011 000000000021 400270000000 000000672000 
000156000200 000154000700 002250370000 600044370120 


Connect Fault ({ 
At: 2701156 ipe 
On: cpu a (#0) 
Indicators: ~ 


2 
| 


) 
156 (bound _command_loop 1156) 


bar 


") 
N 
i] oo) 


trace stack, ts 


® 


APU Status: xsf, sd-on, pt-on, fabs 

CU Status: Tri. Lets, £26 

Instructions: 
4036 002250 3700 O00 epp4 2250 
4037 6 00044 3701 20 epp4 pr6|44,* 


Time stored: 08/02/77 1635.5 edt Tue (104541674361226602) 
Ring: 4 


Backward trace of stack from 244]|]3500 


3500 quit ipc_S$block|156 (bound _command_loop 1156) 
No symbol table for ipe_ 
156 400010116100 empq pr4j10 
ARG 1: 25315704 !BBBIG)FKPBWCNZ.area.linker|5704 
ARG 2: 244/3152 stack 4/3152 
ARG 3: 0 


2720 tty Stty_get_line|2442 (bound_iox [11546) 
No symbol table for tty_ © 
call_ext_out to ipe Sblock 
ARG 1: 25314320 !BBBUIG}FKPBWcNZ.area.linker!4320 
(internal static|1 54 for find toch) 


ARG 2: 24412660 stack 412660 ( -> "fo stuff") 
LRG “32 12g 
ARG 4: QO 
ARG 5: 0 
2400 listen Slisten_1461 (bound _command_loop 11325) 


No symbol table for listen_ 
call_ext_out to iox $get_line 
ARG. leo!" 
on “cleanup” call listen_|256 (bound _command_loop_!1122) 


2100 process overseer Sprocess overseer |473 (bound_command_loop 
\c_ 121433) 
No symbol table for process overseer 
call _ext_out_desc to listen _Slisten_ 
Argument list header invalid. 
on “any other" 
call Standard default handler Sstandard default handler _3 
(external symbol in separate nonstandard text section) 
2000 user_init_admin_Suser_init_admin_{36 (bound_command_loop |2 
\c1676) 


No symbol table for user init admin 
21676 700036670120 tsp4 pr7136,* alm_cail 
No arguments. 
End of trace. 
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r 1635 1.756 40.790 207 level 2, 9 
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Workshops 


Wi 


WORKSHOP ONE 


A probe Workshop 


The best (perhaps the only) way of learning how to use the probe 
command is by using the command in actual debugging sessions. This 
workshop provides the experience of debugging a moderately complicated 
program. The program computes and prints out the elements of a 
Fibonacci series, An F series begins as 


Oud. bed 27a: 6 LS 21 Sa SS wars 


An element of the series is calculated by adding the previous 2 
elements (for a Fibonacci series of degree 2). In the series shown 
above, the first two elements (0 and1) are given as initial values 
and the remaining elements are then computed. 


Fibonacci series of higher degrees can also be defined by adding more 
elements to calculate the next in the series. For example, a series 
of degree 4 begins as ' 


OS 2a St eS 29 36 106 sa 


with the next element of the series calculated by adding the previous 
4 elements in the series. 


The program shown below reads two parameters from the terminal: Fdeg 
gives the number of the highest degree Fibonacci series to be 
computed; count gives the number of elements to be included in each 
series, For input of 


Fdeg=4, count=7; 


the first seven elements (excluding the assumed initial values) of the 
Fibonacci series of degrees 2, 3, and 4 are printed. 


Now, without Further ado, here are the »orograms! There is one written 
in PL/I, and one written in FORTRAN. You can copy whichever of these 


programs you wish to debug from >Dudd>Fl9>Student_ Ol>fib.pli (or 

-fortran) into your home directory. Note that the Line numbers shown 

below are not actually a part of the so'rce segment. ; Cy. 204 
Soe eer 


acer 
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1 fib: proc; ‘ Fe 
2 
3 del (sysin, sysprint) file, 
4 Sfirst bit(]1) int static init("1"b), 
5 (Faec, count, i) fixed Sin, 
6 msg char(256) varying; 
7 
8 dcl linesize fixed bin, 
fe) get_line length Sstream entry (char(*), fixed bin(35)) 
10 returns(fixed bin); 
ii 
2 del cleanup condition; 
13 
14 /* Establish cleanup on unit to close files. “y 
15 /* Open input/output files, get output file line */ 
16 has Rengch to insure output lines fit on al arf 
17 
18 on cleanup close file(sysin), file(sysprint); 
19 open file(sysin) stream input; 
20 open file(sysprint) stream output; 
21 linesize = get_line length Sstream ("“sysprint", 0); 
22 
23 /* Initialize indicator of how many series should */ 
24 /* be output (Fdeg) and how many items should be #*/ 
25 /* output in each series (excluding assumed ait A 
26 7/* initial elements of each series). * / 
27 
28 Fdeg = 2; 
29 count = 10; 
30 
a4 
32 /* Output brief instructions to the user, but * / 
33 haa only the first time fib invoked in each process*/ 
34 
35 if Sfirst then do; 
36 msg = 
37 "Enter Fdeg and/or count, followed by a "";"*" character."; 
38 write file(sysprint) from(msg); ie 
39 msg = 
40 °"For example, 
41 Fdeg = 2, count=10;"; 
42 write file(sysprint) from(msgq) ; 
43 msg = 
44 "These are the default values. To stop, enter 
45 Fdeg = 1; . 
46 of | : 
47 write file(sysprint) from(msg) ; 
48 SEirst = "Ob; 
49 end; 
50 put file(sysprint) 
51 List: CV "ERESr aatay Or Justa. 7s"? chars "3 
52 get file(sysin) data (Fdeg, count); 
53 


Not To Be Reprod 


WORKSHOP ONE 


uced. W-2 LE 21 


Not To 8e Reproduced 


WORKSHOP ONE 


54 | /* Compute and output each Fibonacci series. 
“55: /* Then get next set of input values. 
56. 
57 do while (Fdeg < 1); 
58 “ put file(sysprint) skip(2) data (count); 
539 put file(sysprint) skip; 
602 do i = 2 to Fdeg; 
61. Cali gen, £ib- (iy count); 
62 end; - 
63° put file(sysprint) 
«64 list ("New data, or just a "";"" char: 
oe get file(sysin) data (Fdeg, count); 
66. end; : 
67 - 
68 

oe) ea /* Close files and return. 
70: 7 

a; eens Close file(sysin), file(sysprint);. 

eae : return; 


*/ 


"4 > 


ar 
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74 gen_fib: proc (grouping, count); 


15 
76 del (grouping, count) fixed bin, 
7) /* Fibonacci series to be computed, and number */ 
78 /* of items to be computed in the series. i 
79 N (grouping) fixed bin(71), 
80 /* Array of values summed to form series elements*/ 
81 result (-grouping:count-1) char(28) varying, 
82 /* Array of output values, including assumed id 
83 /* values which begin the series. +7 
84 r_matrix (Nrows, Ncols) char(28) varying based(Pr_matrix), 
85 /* 2-dimensional overlay for the computed output */ 
86 /* values (excluding assumed values). */ 
87 Pr_matrix ptr; 
88 
89 del (Icol, Irow, Ncols, Nrows, 
90 Nused_cols in last_row) fixed bin, 
91 Sdoes not fit bit{1l), 
92 SPACES char(30) int static options(constant) init(**), 
93 cycle fixed bin, 
94 /* index of series element being computed. wy) 
95 EOrmatted total Sic "225,222, 2227222 5222 222,220 3 
96 output total char(100) varying, 
97 total fixed bin(71l); 
98 
99 
100  f/* Initialize the assumed values which begin */ 
101 /* the series. All are 0 but the last, wnich is 1*/ 
102 
103 N(*) = 0; 
104 N(grouping-1) = 1; 
LOS 
106 
107 /* Put the assumed values in the output array. at 
108 
109 do cycle = -grouping to -2; 
Lio result(cycle) = "0"; 
Baa aA end; 
122 result(cycle) = "1"; 
+7 
114 
LS /* Compute remaining values of series, and put in */ 
116 /* the output array. ui A 
pay 
ae do cycle = 0 to count-1; 
119 total = sum(N); 
120 formatted total = total; 
121 result(cycle) = ltrim(formatted_ total); 
122 N(mod(cycle, grouping)) = total; 
123 end; 
124 
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L225 /* The output will be printed with assumed values */ 
126 /* preceding computed values. The computed values*/ 
127 /* will be printed in as many rows as possible to */ 
128 /* reduce the number of output lines. However, if*/ 
129 /* the output fits in 2 or more rows, the number */ 
130 /* of rows is chosen so that all columns but the */ 
ye /* final one are full (have Nrows values). * / 
132 /* Of course, in multi-column format, all data * / 
133 7/* must fit the terminal linesize. * / 
134 

135 Pr matrix = addr{result(0)); 

136 Sdoes not fit = "1%; 

L337 do Ncols = 20 to 1 by -l1 while (Sdoes not_fit); 

138 total = =2; 

139 Nrows = divide(count+Ncols-1, Ncols, 17, 0); 
140 Nused cols in last row = mod(count,Ncols); 

141 if Nused cols in_ last row = 0 then 

142 Nused_cols In_last_row = Ncols; 

143 if Nused cols in_ last row >= Ncols then do; 

144 do Icol = 1 to Nused_cols_in_last_row; 

145 total = total + 

146 length(r_ matrix (rest, Nrows))+2 
147 end; 

148 do Icol = icol to. Neols: 

149 | total = total + 

150 length(r_matrix(icol, NrowsS-1))+2 
151 end; 

152 if total <= linesize then Sdoes not fit = "“O"b; 
155 end; | 

154 end; 

LoD Ncols = Ncols + 1; 

156 
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157 /* Output the values, starting with the assumed */ 
158 /* values, then the computed (output in columns). */ 
159 /* Computed values are output in right-justified */ 
160 7/*® columns. Each row (line) is formatted and * / 
161 /* then output. 7 
162 
163 put file(sysprint) edit ("Fdeg =", grouping, 
164 ier) [Geigy SEC) pe eens 
165 put file(sysprint) edit ("(assumed beginning of series)", 
166 (result(cycle) do cycle=-grouping to -1)) 
167 (skip, a, skip, (grouping) (a, x(1))); 
168 put file{sysprint) 
169 edit ("“(remainder of series)") (skip, a); 
LO put file(sysprint) skip; 
171 do Irow = 1 to Nrows; 
172 msg = ""; 
173 do Icol = 1 to Necols-1l; 
174 msg = msg || substr(SPACES, l, 
Lis length (r_matrix(Icol,Nrows)) - 
176 length(r matrix(Icol,Irow))); 
177 msg = msg || r_matrix(Icol, Irow); 
178 msg = msg || " "; 
179 end; 
180 lf ITrow*Ncols + Icol <= count then do; 
181 msg = msg || substr(SPACES, l, 
182 length(result{(hbound(result,1)}) - 
183 . length(r_matrix(Icol, Irow))); 
184 msg = msg || r_matrix(Icol, Irow)- 
185 end; : i 
186 write file(sysprint) from(msg); | 
187 end; 
188 put skip(2) file(sysprint); 
189 end gen_fib; 
190 
191 end fib; 
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A FORTRAN VERSION 


logical sfirst /.true./ 
save sfirst 


Output instructions to the user, but only the first 
time 'fib' is invoked in each process. 


Lf. { snot. Stirst). .gote: 10 
print, "Enter first degree and count" 
print, "For example, First degree = 2, count = 10" 


print, "To stop, enter First degree = 1" 
sfirst = .false. 


Prompt for First degree and count. 
print, "First degree, count?" 
read, ifdeg, icount 


Stop when First degree is l. 
rf (ifdeq = 1.) 15,15,25 


Drint;, “Count =",;icount 


Compute and output each Fibonacci series. 
Then get next set of input values. 


do 22 i = 2,ifdeg 
call gen_fib (i,icount) 


goto 10 


stop 
end 


subroutine gen_fib (igrouping, icount) 


This subroutine actually computes the Fibonacci series. 
‘iresult' will be filled with the proper values, 
while ‘jresuit' is a convenient equivalent view of 
the solution which will be used for printing purposes. 
The 'n' array holds the most recent terms to be added 
together to obtain the next term in the series. 


double precision n(10), total 
dimension iresult(30) 

dimension jresult(10,3) 

equivalence (iresult(1),jresult(1,1)) 


“ 


Tell him which degree of Fibonacci series this i 


Print 
print,"Degree =",igrouping 
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52 print 

53 

54 c Initialize the assumed values which begin the 
55 c series, All are 0 but the last, which is 

56 c 1 = also put the assumed values into the 

=e c output array 

58 

59 do 10 i = l,igrouping-1 

60 iresult(i) = 0 

61 10 n(i) = 0 

62 iresult(igrouping) = 1 

63 n(igrouping) = 1 

64 

65 c Compute remaining values of series, and put in 
66 c the output array 

67 

68 do 20 icycle = igrouping+1l, icount 

69 total = 0 

70 do 15 i=l, igrouping 

eh 15 total = total + n(i) 

72 iresult(icycle) = total 

13 20 n(mod(icycle-l,igrouping)) = total 

74 

795 c The output will be printed with assumed values 
76 cS preceding computed values. The computed values 
va ec will be printed along with the assumed values 
78 c in three columns. Hence, there will always be 
79 c ‘irow' rows with three values, and the last - 
80 Cc row may have 1 2 or 3 values 

81 

82 * icol = mod(icount,3) 

83 irow = icount / 3 

84 

85 do 22 j=l,irow 

86 22 BLAne,jresule(i.7)7tSh;3) 

87 if (ico2),..30,30525 

88 25 print, (jresult(irow+l,i) ,i=1,icol) 

89 30 return 

30 end 
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The following dialogue shows the correct operation of the PL/I version 
of the fib program. The dialogue is slightly different for the 
FORTRAN and COBOL versions, but the concept is basically the same for 
all three programs. The programs shown above may have errors which 
prevent them from generating these results. Use probe to find the 
errors. Change the source to correct ‘the errors, recompile the 
program and continue testing it until it prints the results shown 
below. 


fe tas ge ee eg Nn 


! 4.  ., pll fib -table | 
a PL/I | 
| 3 E2247 S009) iSla3l2. 227 | 
| 4 | 
5 ! fib | 
| 6 Enter Fdeg and/or count, followed by a “;" character. | 
| 7 For example, | 
| 8 Fdeg = 2, count=10; | 
| 9 These are the default values. To stop, enter | 
i 0 Fdeg = 1; | 
() ah | 
| 12 Enter data, or just a “;" char: 1 Fdeg = 4, count=9; 
| 13 | 
| 14 | 
[i hs count= 9; | 
| 16 Fdeg = 2: | 
| a ae beginning of series) | 
| 19 (remainder of series) | 
| 20 i -2 3 & -6 £3 22 34: .95 | 
|} 21 . 3 | 
Ii’ 22 | 
| 23 Fdeg = 3: | 
| 24 (assumed beginning of series) | 
| 25 OQ: 3k | 
| 26 (remainder of series) 
| 27 1 2 4 7 13 24 #44 #81 4149 | 
| 28 | 
| 29 | 
| 30 Fdeg = 4: | 
| 32 (assumed beginning of series) | 
| 32 0°0). 30° 2 | 
| 33 (remainder of series) | 
| 34 12 4 8 15 29 56 108 208 | 
L 3S | 
| 36 | 
7 New data, or just a ";" char: ! Fdeg=1l; | 
| 38 r 2248 0.249 0.228 19 | 
| 
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A trace Workshop 


1. Use ‘trace’ to monitor the value of the arguments on return from 
the system program ‘expand pathname ' (trace “ag lL out 
expand pathname _). Do you know what that program is used for? 
Issue the trace command to list the status of the expand _pathname_ 
trace entry (trace -status expand _pathname_ ). Do you know what 
those counters mean? Now issue a print command and observe what 
happens. Issue the command ‘print >ldd>include>its.incl.pll' and 
see what happens. Now try the command ‘ds baloney’. Finally, try 
the command 'pr <>foo'. What happens? What do you think the 
fourth argument of expand _pathname_ is used for?? 


2. Now print the status of the expand _pathname_ (trace -status 
expand pathname ). Also, list the control template for trace 
(trace -tp). Remove the trace entry for expand pathname_ and 


reset the control template to its initial form (trace -remove 
expand _pathname_-ag 0). 


> fSoed 7 wksP5 7 FAI7SID 


3. Execute the following recursive program (see >udd>F19>sl>R2.pl1l 
and >udd>F19>s1>R2): 


R2e. procs 

dcl (sysin, sysprint) file; 
del (n, i} fixed bin; 

del R2SSeq entry (fixed bin); 


epen file (sysprint) stream output env (interactive); 
put file (sysprint) skip list ("Enter value..."); 

get list (n); 

call R2SSeq (n); 

return; 


Seq: entry (i); 
put file (sysprint) list (i); 
if i> 1 then do; 
call R2SSeq (i-1); 
put file (sysprint) list (i); 
end; 
end; 


Execute the program with a value of 5. You should get 54321 2 
3 4 5. Type the command to trace this program, printing the 
argument values at input to every second call(trace -in -ag 2 
R2SSeq). Now run R2 again using the value 5 and observe what 
happens. List the trace status of R2SSeq and then turn on the 
governing facility (trace -st R2$Seq -govern on R2SSeq). The 
governing facility is used to help trap runaway recursive 
procedures. Run R2 once again, using the value 5. List the 
Status of R2SSeq(trace -st R2$Seq). Note the maximum recursion 
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level. Now lets see if we can blow it out. Run R2 again, this 
time with an input of 12. What happened? Since our procedure is 
not really a runaway program, type the ‘start' command to 
continue. Did you realize that we were at command level? 
Why? (Hint: the govern facility stops on depth levels which are a 
multiple of 10 to give you a chance to find out what's happening). 


Now, stop tracing R2SSeq, and reset the template. You may first 
want to issue the command ‘trace -st * -tp' to see the current 
State of affairs. Next, copy the following three simple pll 
programs, which are found in the directory >udd>F1l9>sl: 


LALEs DEO; 
dcl 1 S external static, 
2 sentinel fixed bin, 
2 array (5) float; 
del ioa_ entry options (variable); 
del addr builtin; 


sentinel = 0; 
call ioa_ ("Sentinel located at *p", addr (sentinel)); 
end; 


load: proc; 

acl. sysprint: file: 

dcl 1S external static, 
2 sentinel fixed bin, 
2 array (5) float; 

dcl i fixed bin; 


open file (sysprint) stream output env (interactive); 
do iz=1 to 5; 
array (i) = 3* (i-2); 
end; 
put file (sysprint) skip (3) list (array); 
end; 


Not To Be Reproduced W-1il F2i 


WORKSHOP TWO 


print stat: proc; 

del Sysprint file; 

del 1S external static, 
2 sentinel fixed bin, 
2 array (5) float; 


open file (sysprint) stream output env (interactive); 
put skip (2) lisr ("*sentinel location clobbered!!*"); 
put skip (1) data (S); 

end; 


Compile each of these programs. Now run init. It should tell you 
that the external static member variable 'sentinel' is located at 
some segment numberloffset. We want to use the watch facility of 
trace to find out whether any program is clobbering that location. 
Hence, issue the command to have trace watch that location ~=saeece 
*watch seg noloffset). Next, let's monitor the ‘load! program, 
and if anything goes wrong, let's cause the print_stat program to 
be called as the ‘stop proc' instead of the command processor. 
Issue the command to do this(trace -stop proc print stat load). 
Now run the load program and see what happens. So far so good! 
Now modify the load program so that it inadvertently changes the 
value of sentinel by changing the ‘do' statement to ‘do i= 0 to 
5'. Recompile and run the load program. What happens? The watch 
facility should have stopped your load orogram since the value of 
its watch location changed, and it should have called the 
appropriate ‘stop ‘proc’. Bra hee The watch facility is.very 
useful when trying to track down the one procedure in a group of 
procedures that is going a bit awry, or has modified some 
externally accessible error cell,etc. 
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On the Programming Environment: A Quiz 


de Object segments are an essential part of the Multics programming 
environment. Name the 8 sections into which an object segment is 
divided. Describe the contents of each section in general terms. 
Are all the sections always present in every object segment? If 
not, which are optional. 
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2. The system maintains information about the user ring programming 
environment in 2 important segments. Can you name these 2 
segments? Briefly describe what kinds of data the system keeps 
in each segment. What directory are the segments located in? 
How are these segments protected from accidental damage? 
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34 One of the most powerful features of the Multics programming 
environment is the Dynamic Linking mechanism. The programming 
environment uses this mechanism to find an object segment which 
is called by another program. 


Briefly name the important steps taken by the dynamic linker to 
Eind an object segment. 


At what point during the compilation or execution of the calling 
program does dynamic linking take place? 


How often dois it take place? 


If one program calls an object segment and then a second program 
(a second ob*ect segment) calls that same target object segment, 
are the same steps followed in both cases to dynamically link to 
the called object segment? If not, how does dynamic linking 
differ during the second call? 
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4, A fatal process error occurs when the system decides “hat the 
programming environment can no longer operate correctly. When 
this occurs, the system takes control of the user's terminal, 
prints a brief error message, and creates a new user process. 


Under what circumstances might the system decide that the 


pr..cPtog ramming environment can no longer operate? 
won tee 


What 2 programming errors are the most common causes of fatal 
process errors? 


Briefly describe a procedure for finding the cause of a fatal 
process error. 
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3% In chapter four 11 different classes of data (storage classes) - 
were discussed which can be used in PL/I, FORTRAN and/or COBCL . 
programs. For each class of data, describe: 


fe) Where the data is stored. Give the logical name of 
segment, table, or area; also give the pathname of the 
segment containing the data class. 


° The major characteristics of the storage class. (When the 
data is allocated, when freed, when initialized, can it be 
shared between programs, etc?) 4 


Ln vinascel 


For example, one class of storage is: 


based storage, in an area: stored in a program-supplied area, 
such as the system free area (segment system_free n_ in the 
process dir). Storage is known only to 1 program, is 


explicitly allocated and freed, is initialized by allocate 
or locate statements, and has a location maintained by a 
pointer or offset qualifier. 
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5. (More space-for the answer) 


aad aed . 


\ PR oe ie oS pe See ety eo Ge Teg ee ao edt 


\.../ Happiness is Multing the day away \ 
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